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 ex. 

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 exref_node(nodes.admonition): 

13 """ 

14 defines ``exref`` ndoe 

15 """ 

16 pass 

17 

18 

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

20 """ 

21 defines ``exreflist`` node 

22 """ 

23 pass 

24 

25 

26class ExRef(BlocRef): 

27 """ 

28 A ``exref`` 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 (optional) 

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

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

35 

36 Example:: 

37 

38 .. exref:: 

39 :title: example of a blocref 

40 :lid: id-you-can-choose6 

41 

42 An example of code: 

43 

44 :: 

45 

46 print("mignon") 

47 

48 Which renders as: 

49 

50 .. exref:: 

51 :title: example of a exref 

52 :tag: dummy_example6 

53 :lid: id-you-can-choose6 

54 

55 An example of code: 

56 

57 :: 

58 

59 print("mignon") 

60 

61 All blocs can be displayed in another page by using ``exreflist``:: 

62 

63 .. exreflist:: 

64 :tag: dummy_example6 

65 :sort: title 

66 

67 Only blocs tagged as ``dummy_example`` will be inserted here. 

68 The option ``sort`` sorts items by *title*, *number*, *file*. 

69 You also link to it by typing ``:ref:'anchor <id-you-can-choose2>'`` which gives 

70 something like :ref:`link_to_blocref <id-you-can-choose2>`. The link must receive a name. 

71 

72 .. exreflist:: 

73 :tag: dummy_example6 

74 :sort: title 

75 """ 

76 

77 node_class = exref_node 

78 name_sphinx = "exref" 

79 

80 def run(self): 

81 """ 

82 calls run from @see cl BlocRef and add defaut tag 

83 """ 

84 if "tag" not in self.options: 

85 self.options["tag"] = "ex" 

86 return BlocRef.run(self) 

87 

88 

89def process_exrefs(app, doctree): 

90 """ 

91 collect all *exref* in the environment 

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

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

94 """ 

95 process_blocrefs_generic( 

96 app, doctree, bloc_name="exref", class_node=exref_node) 

97 

98 

99class ExRefList(BlocRefList): 

100 """ 

101 A list of all *exref* entries, for a specific tag. 

102 

103 * tag: a tag to filter bloc having this tag 

104 * sort: a way to sort the blocs based on the title, file, number, default: *title* 

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

106 

107 Example:: 

108 

109 .. exreflist:: 

110 :tag: issue 

111 """ 

112 name_sphinx = "exreflist" 

113 node_class = exreflist 

114 

115 def run(self): 

116 """ 

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

118 """ 

119 if "tag" not in self.options: 

120 self.options["tag"] = "ex" 

121 return BlocRefList.run(self) 

122 

123 

124def process_exref_nodes(app, doctree, fromdocname): 

125 """ 

126 process_blocref_nodes 

127 """ 

128 process_blocref_nodes_generic(app, doctree, fromdocname, class_name='exref', 

129 entry_name="exmes", class_node=exref_node, 

130 class_node_list=exreflist) 

131 

132 

133def purge_exrefs(app, env, docname): 

134 """ 

135 purge_exrefs 

136 """ 

137 if not hasattr(env, 'exref_all_exrefs'): 

138 return 

139 env.exref_all_exrefs = [exref for exref in env.exref_all_exrefs 

140 if exref['docname'] != docname] 

141 

142 

143def merge_exref(app, env, docnames, other): 

144 """ 

145 merge_exref 

146 """ 

147 if not hasattr(other, 'exref_all_exrefs'): 

148 return 

149 if not hasattr(env, 'exref_all_exrefs'): 

150 env.exref_all_exrefs = [] 

151 env.exref_all_exrefs.extend(other.exref_all_exrefs) 

152 

153 

154def visit_exref_node(self, node): 

155 """ 

156 visit_exref_node 

157 """ 

158 self.visit_admonition(node) 

159 

160 

161def depart_exref_node(self, node): 

162 """ 

163 depart_exref_node, 

164 see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py 

165 """ 

166 self.depart_admonition(node) 

167 

168 

169def visit_exreflist_node(self, node): 

170 """ 

171 visit_exreflist_node 

172 see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py 

173 """ 

174 self.visit_admonition(node) 

175 

176 

177def depart_exreflist_node(self, node): 

178 """ 

179 depart_exref_node 

180 """ 

181 self.depart_admonition(node) 

182 

183 

184def setup(app): 

185 """ 

186 setup for ``exref`` (sphinx) 

187 """ 

188 if hasattr(app, "add_mapping"): 

189 app.add_mapping('exref', exref_node) 

190 app.add_mapping('exreflist', exreflist) 

191 

192 app.add_config_value('exref_include_exrefs', True, 'html') 

193 app.add_config_value('exref_link_only', False, 'html') 

194 

195 app.add_node(exreflist, 

196 html=(visit_exreflist_node, depart_exreflist_node), 

197 epub=(visit_exreflist_node, depart_exreflist_node), 

198 elatex=(visit_exreflist_node, depart_exreflist_node), 

199 latex=(visit_exreflist_node, depart_exreflist_node), 

200 tex=(visit_exreflist_node, depart_exreflist_node), 

201 text=(visit_exreflist_node, depart_exreflist_node), 

202 md=(visit_exreflist_node, depart_exreflist_node), 

203 rst=(visit_exreflist_node, depart_exreflist_node)) 

204 app.add_node(exref_node, 

205 html=(visit_exref_node, depart_exref_node), 

206 epub=(visit_exref_node, depart_exref_node), 

207 elatex=(visit_exref_node, depart_exref_node), 

208 latex=(visit_exref_node, depart_exref_node), 

209 tex=(visit_exref_node, depart_exref_node), 

210 text=(visit_exref_node, depart_exref_node), 

211 md=(visit_exref_node, depart_exref_node), 

212 rst=(visit_exref_node, depart_exref_node)) 

213 

214 app.add_directive('exref', ExRef) 

215 app.add_directive('exreflist', ExRefList) 

216 app.connect('doctree-read', process_exrefs) 

217 app.connect('doctree-resolved', process_exref_nodes) 

218 app.connect('env-purge-doc', purge_exrefs) 

219 app.connect('env-merge-info', merge_exref) 

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