Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

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

2""" 

3@file 

4@brief Defines a :epkg:`sphinx` extension to keep track of nb. 

5""" 

6from docutils import nodes 

7 

8import sphinx 

9from .sphinx_blocref_extension import BlocRef, process_blocrefs_generic, BlocRefList, process_blocref_nodes_generic 

10 

11 

12class nbref_node(nodes.admonition): 

13 """ 

14 defines ``nbref`` ndoe 

15 """ 

16 pass 

17 

18 

19class nbreflist(nodes.General, nodes.Element): 

20 """ 

21 defines ``nbreflist`` node 

22 """ 

23 pass 

24 

25 

26class NbRef(BlocRef): 

27 """ 

28 A ``nbref`` entry, displayed in the form of an admonition. 

29 It takes the following options: 

30 

31 * *title*: a title for the bloc 

32 * *tag*: a tag to have several categories of blocs, if not specified, it will be equal to *nb* 

33 * *lid* or *label*: a label to refer to 

34 * *index*: to add an additional entry to the index (comma separated) 

35 

36 See :ref:`%encrypt_file <l-nb-encrypt-file>` for an example. 

37 All entries can be aggregated per tag with ``nbreflist``:: 

38 

39 .. nbreflist:: 

40 :tag: dummy_example2 

41 :sort: title 

42 

43 It works the same way as @see cl BlocRef. 

44 """ 

45 

46 node_class = nbref_node 

47 name_sphinx = "nbref" 

48 

49 def run(self): 

50 """ 

51 calls run from @see cl BlocRef and add index entries by default 

52 """ 

53 if 'title' not in self.options: 

54 lineno = self.lineno 

55 env = self.state.document.settings.env if hasattr( 

56 self.state.document.settings, "env") else None 

57 docname = None if env is None else env.docname 

58 raise KeyError( # pragma: no cover 

59 "Unable to find 'title' in node {0}\n File \"{1}\", " 

60 "line {2}\nkeys: {3}".format( 

61 str(self.__class__), docname, lineno, 

62 list(self.options.keys()))) 

63 title = self.options['title'] 

64 if "tag" not in self.options: 

65 self.options["tag"] = "nb" 

66 if "index" not in self.options: 

67 self.options["index"] = title 

68 else: 

69 self.options["index"] += "," + title 

70 return BlocRef.run(self) 

71 

72 

73def process_nbrefs(app, doctree): 

74 """ 

75 Collect all *nbref* in the environment 

76 this is not done in the directive itself because it some transformations 

77 must have already been run, e.g. substitutions. 

78 """ 

79 process_blocrefs_generic( 

80 app, doctree, bloc_name="nbref", class_node=nbref_node) 

81 

82 

83class NbRefList(BlocRefList): 

84 """ 

85 A list of all *nbref* entries, for a specific tag. 

86 

87 * tag: a tag to have several categories of nbref 

88 * contents: add a bullet list with links to added blocs 

89 

90 Example:: 

91 

92 .. nbreflist:: 

93 :tag: issue 

94 """ 

95 name_sphinx = "nbreflist" 

96 node_class = nbreflist 

97 

98 def run(self): 

99 """ 

100 calls run from @see cl BlocRefList and add default tag if not present 

101 """ 

102 if "tag" not in self.options: 

103 self.options["tag"] = "nb" 

104 return BlocRefList.run(self) 

105 

106 

107def process_nbref_nodes(app, doctree, fromdocname): 

108 """ 

109 process_nbref_nodes 

110 """ 

111 process_blocref_nodes_generic(app, doctree, fromdocname, class_name='nbref', 

112 entry_name="nbmes", class_node=nbref_node, 

113 class_node_list=nbreflist) 

114 

115 

116def purge_nbrefs(app, env, docname): 

117 """ 

118 purge_nbrefs 

119 """ 

120 if not hasattr(env, 'nbref_all_nbrefs'): 

121 return 

122 env.nbref_all_nbrefs = [nbref for nbref in env.nbref_all_nbrefs 

123 if nbref['docname'] != docname] 

124 

125 

126def merge_nbref(app, env, docnames, other): 

127 """ 

128 merge_nbref 

129 """ 

130 if not hasattr(other, 'nbref_all_nbrefs'): 

131 return 

132 if not hasattr(env, 'nbref_all_nbrefs'): 

133 env.nbref_all_nbrefs = [] 

134 env.nbref_all_nbrefs.extend(other.nbref_all_nbrefs) 

135 

136 

137def visit_nbref_node(self, node): 

138 """ 

139 visit_nbref_node 

140 """ 

141 self.visit_admonition(node) 

142 

143 

144def depart_nbref_node(self, node): 

145 """ 

146 *depart_nbref_node*, 

147 see `sphinx/writers/html.py <https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py>`_. 

148 """ 

149 self.depart_admonition(node) 

150 

151 

152def visit_nbreflist_node(self, node): 

153 """ 

154 *visit_nbreflist_node*, 

155 see `sphinx/writers/html.py <https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py>`_. 

156 """ 

157 self.visit_admonition(node) 

158 

159 

160def depart_nbreflist_node(self, node): 

161 """ 

162 depart_nbref_node 

163 """ 

164 self.depart_admonition(node) 

165 

166 

167def setup(app): 

168 """ 

169 setup for ``nbref`` (sphinx) 

170 """ 

171 if hasattr(app, "add_mapping"): 

172 app.add_mapping('nbref', nbref_node) 

173 app.add_mapping('nbreflist', nbreflist) 

174 

175 app.add_config_value('nbref_include_nbrefs', True, 'html') 

176 app.add_config_value('nbref_link_only', False, 'html') 

177 

178 app.add_node(nbreflist, 

179 html=(visit_nbreflist_node, depart_nbreflist_node), 

180 epub=(visit_nbreflist_node, depart_nbreflist_node), 

181 elatex=(visit_nbreflist_node, depart_nbreflist_node), 

182 latex=(visit_nbreflist_node, depart_nbreflist_node), 

183 text=(visit_nbreflist_node, depart_nbreflist_node), 

184 md=(visit_nbreflist_node, depart_nbreflist_node), 

185 rst=(visit_nbreflist_node, depart_nbreflist_node)) 

186 app.add_node(nbref_node, 

187 html=(visit_nbref_node, depart_nbref_node), 

188 epub=(visit_nbref_node, depart_nbref_node), 

189 elatex=(visit_nbref_node, depart_nbref_node), 

190 latex=(visit_nbref_node, depart_nbref_node), 

191 text=(visit_nbref_node, depart_nbref_node), 

192 md=(visit_nbref_node, depart_nbref_node), 

193 rst=(visit_nbref_node, depart_nbref_node)) 

194 

195 app.add_directive('nbref', NbRef) 

196 app.add_directive('nbreflist', NbRefList) 

197 app.connect('doctree-read', process_nbrefs) 

198 app.connect('doctree-resolved', process_nbref_nodes) 

199 app.connect('env-purge-doc', purge_nbrefs) 

200 app.connect('env-merge-info', merge_nbref) 

201 return {'version': sphinx.__display_version__, 'parallel_read_safe': True}