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
8import sphinx
9from .sphinx_blocref_extension import BlocRef, process_blocrefs_generic, BlocRefList, process_blocref_nodes_generic
12class exref_node(nodes.admonition):
13 """
14 defines ``exref`` ndoe
15 """
16 pass
19class exreflist(nodes.General, nodes.Element):
20 """
21 defines ``exreflist`` node
22 """
23 pass
26class ExRef(BlocRef):
27 """
28 A ``exref`` entry, displayed in the form of an admonition.
29 It takes the following options:
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)
36 Example::
38 .. exref::
39 :title: example of a blocref
40 :lid: id-you-can-choose6
42 An example of code:
44 ::
46 print("mignon")
48 Which renders as:
50 .. exref::
51 :title: example of a exref
52 :tag: dummy_example6
53 :lid: id-you-can-choose6
55 An example of code:
57 ::
59 print("mignon")
61 All blocs can be displayed in another page by using ``exreflist``::
63 .. exreflist::
64 :tag: dummy_example6
65 :sort: title
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.
72 .. exreflist::
73 :tag: dummy_example6
74 :sort: title
75 """
77 node_class = exref_node
78 name_sphinx = "exref"
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)
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)
99class ExRefList(BlocRefList):
100 """
101 A list of all *exref* entries, for a specific tag.
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
107 Example::
109 .. exreflist::
110 :tag: issue
111 """
112 name_sphinx = "exreflist"
113 node_class = exreflist
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)
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)
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]
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)
154def visit_exref_node(self, node):
155 """
156 visit_exref_node
157 """
158 self.visit_admonition(node)
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)
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)
177def depart_exreflist_node(self, node):
178 """
179 depart_exref_node
180 """
181 self.depart_admonition(node)
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)
192 app.add_config_value('exref_include_exrefs', True, 'html')
193 app.add_config_value('exref_link_only', False, 'html')
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))
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}