1# -*- coding: utf-8 -*- 

2""" 

3@file 

4@brief Example of a class which defines magic commands. 

5""" 

6from __future__ import print_function 

7from IPython.core.magic import magics_class, line_magic 

8from .magic_class import MagicClassWithHelpers 

9from .magic_parser import MagicCommandParser 

10from ..helpgen import docstring2html 

11 

12 

13@magics_class 

14class MagicClassExample(MagicClassWithHelpers): 

15 

16 """ 

17 .. faqref:: 

18 :title: Define a magic command 

19 

20 This class is an example of how a magic commands can be defined 

21 with parameters as if it was a regular command in a terminal. 

22 The class @see cl MagicClassExample defines magic 

23 command ``htmlhelp`` and the associated parser. 

24 Function @see fn load_ipython_extension 

25 register the magic command through ``%load_ext pyquickhelper``. 

26 The magic command can be unit tested with:: 

27 

28 mg = MagicClassExample() 

29 mg.add_context(context={"MagicClassExample": MagicClassExample}) 

30 cmd = "MagicClassExample -f text" 

31 res = mg.htmlhelp(cmd) 

32 assert "NB(example of a magic command)" 

33 """ 

34 

35 @staticmethod 

36 def htmlhelp_parser(): 

37 """ 

38 Defines the way to parse the magic command ``%htmlhelp``. 

39 """ 

40 parser = MagicCommandParser(prog="htmlhelp", 

41 description='display help for an object in HTML format') 

42 parser.add_argument( 

43 'obj', 

44 type=str, 

45 help='a python object') 

46 parser.add_argument( 

47 '-f', 

48 '--format', 

49 type=str, 

50 default="html", 

51 help='format', 

52 choices=['text', 'html', 'rst', 'rawhtml']) 

53 parser.add_argument( 

54 '-np', 

55 '--no-print', 

56 action='store_true', 

57 help='by default, the magic command outputs everything on the standard output, ' 

58 'if specified, it returns a string') 

59 return parser 

60 

61 @line_magic 

62 def htmlhelp(self, line): 

63 """ 

64 Defines ``%htmlhelp``, it displays the help for an object in :epkg:`HTML`. 

65 

66 .. nbref:: 

67 :title: %htmlhelp 

68 

69 Magic command ``htmlhelp`` convert docstring (RST) 

70 into HTML format for a better display in a notebook. 

71 It is equivalent to the code: 

72 

73 :: 

74 

75 from pyquickhelper.helpgen import docstring2html 

76 obj = <function or object> 

77 docstring2html(obj, format="html") 

78 

79 See function @see fn docstring2html. 

80 """ 

81 parser = self.get_parser(MagicClassExample.htmlhelp_parser, "htmlhelp") 

82 args = self.get_args(line, parser) 

83 

84 if args is not None: 

85 obj = args.obj 

86 format = args.format 

87 nop = args.no_print 

88 if nop or format == "html": 

89 return docstring2html(obj, format=format) 

90 print(docstring2html(obj, format=format)) 

91 return None # pragma: no cover 

92 

93 

94def register_file_magics(ip=None): # pragma: no cover 

95 """ 

96 Registers magics functions, can be called from a notebook. 

97 

98 @param ip from ``get_ipython()`` 

99 """ 

100 if ip is None: 

101 from IPython import get_ipython 

102 ip = get_ipython() 

103 ip.register_magics(MagicClassExample)