Coverage for pyquickhelper/sphinxext/sphinx_nbref_extension.py: 84%
67 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-03 02:21 +0200
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-03 02:21 +0200
1# -*- coding: utf-8 -*-
2"""
3@file
4@brief Defines a :epkg:`sphinx` extension to keep track of nb.
5"""
6from docutils import nodes
8import sphinx
9from .sphinx_blocref_extension import BlocRef, process_blocrefs_generic, BlocRefList, process_blocref_nodes_generic
12class nbref_node(nodes.admonition):
13 """
14 defines ``nbref`` ndoe
15 """
16 pass
19class nbreflist(nodes.General, nodes.Element):
20 """
21 defines ``nbreflist`` node
22 """
23 pass
26class NbRef(BlocRef):
27 """
28 A ``nbref`` 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, 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)
36 See :ref:`%encrypt_file <l-nb-encrypt-file>` for an example.
37 All entries can be aggregated per tag with ``nbreflist``::
39 .. nbreflist::
40 :tag: dummy_example2
41 :sort: title
43 It works the same way as @see cl BlocRef.
44 """
46 node_class = nbref_node
47 name_sphinx = "nbref"
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)
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)
83class NbRefList(BlocRefList):
84 """
85 A list of all *nbref* entries, for a specific tag.
87 * tag: a tag to have several categories of nbref
88 * contents: add a bullet list with links to added blocs
90 Example::
92 .. nbreflist::
93 :tag: issue
94 """
95 name_sphinx = "nbreflist"
96 node_class = nbreflist
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)
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)
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]
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)
137def visit_nbref_node(self, node):
138 """
139 visit_nbref_node
140 """
141 self.visit_admonition(node)
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)
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)
160def depart_nbreflist_node(self, node):
161 """
162 depart_nbref_node
163 """
164 self.depart_admonition(node)
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)
175 app.add_config_value('nbref_include_nbrefs', True, 'html')
176 app.add_config_value('nbref_link_only', False, 'html')
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))
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}