Coverage for pyquickhelper/sphinxext/sphinx_faqref_extension.py: 88%
59 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 FAQ.
5"""
6from docutils import nodes
8import sphinx
9from .sphinx_blocref_extension import BlocRef, process_blocrefs_generic, BlocRefList, process_blocref_nodes_generic
12class faqref_node(nodes.admonition):
13 """
14 defines ``faqref`` ndoe
15 """
16 pass
19class faqreflist(nodes.General, nodes.Element):
20 """
21 defines ``faqreflist`` node
22 """
23 pass
26class FaqRef(BlocRef):
27 """
28 A ``faqref`` 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 .. faqref::
39 :title: example of a blocref
40 :lid: id-you-can-choose
42 An example of code:
44 ::
46 print("mignon")
48 Which renders as:
50 .. faqref::
51 :title: example of a faqref
52 :tag: dummy_example2
53 :lid: id-you-can-choose2
55 An example of code:
57 ::
59 print("mignon")
61 All blocs can be displayed in another page by using ``faqreflist``::
63 .. faqreflist::
64 :tag: dummy_example2
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 .. faqreflist::
73 :tag: dummy_example2
74 :sort: title
75 """
77 node_class = faqref_node
78 name_sphinx = "faqref"
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"] = "faq"
86 return BlocRef.run(self)
89def process_faqrefs(app, doctree):
90 """
91 collect all *faqref* 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="faqref", class_node=faqref_node)
99class FaqRefList(BlocRefList):
100 """
101 A list of all *faqref* 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 .. faqreflist::
110 :tag: issue
111 :contents:
112 """
113 name_sphinx = "faqreflist"
114 node_class = faqreflist
116 def run(self):
117 """
118 calls run from @see cl BlocRefList and add default tag if not present
119 """
120 if "tag" not in self.options:
121 self.options["tag"] = "faq"
122 return BlocRefList.run(self)
125def process_faqref_nodes(app, doctree, fromdocname):
126 """
127 process_faqref_nodes
128 """
129 process_blocref_nodes_generic(app, doctree, fromdocname, class_name='faqref',
130 entry_name="faqmes", class_node=faqref_node,
131 class_node_list=faqreflist)
134def purge_faqrefs(app, env, docname):
135 """
136 purge_faqrefs
137 """
138 if not hasattr(env, 'faqref_all_faqrefs'):
139 return
140 env.faqref_all_faqrefs = [faqref for faqref in env.faqref_all_faqrefs
141 if faqref['docname'] != docname]
144def merge_faqref(app, env, docnames, other):
145 """
146 merge_faqref
147 """
148 if not hasattr(other, 'faqref_all_faqrefs'):
149 return
150 if not hasattr(env, 'faqref_all_faqrefs'):
151 env.faqref_all_faqrefs = []
152 env.faqref_all_faqrefs.extend(other.faqref_all_faqrefs)
155def visit_faqref_node(self, node):
156 """
157 visit_faqref_node
158 """
159 self.visit_admonition(node)
162def depart_faqref_node(self, node):
163 """
164 depart_faqref_node,
165 see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py
166 """
167 self.depart_admonition(node)
170def visit_faqreflist_node(self, node):
171 """
172 visit_faqreflist_node
173 see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py
174 """
175 self.visit_admonition(node)
178def depart_faqreflist_node(self, node):
179 """
180 depart_faqref_node
181 """
182 self.depart_admonition(node)
185def setup(app):
186 """
187 setup for ``faqref`` (sphinx)
188 """
189 if hasattr(app, "add_mapping"):
190 app.add_mapping('faqref', faqref_node)
191 app.add_mapping('faqreflist', faqreflist)
193 app.add_config_value('faqref_include_faqrefs', True, 'html')
194 app.add_config_value('faqref_link_only', False, 'html')
196 app.add_node(faqreflist,
197 html=(visit_faqreflist_node, depart_faqreflist_node),
198 epub=(visit_faqreflist_node, depart_faqreflist_node),
199 elatex=(visit_faqreflist_node, depart_faqreflist_node),
200 latex=(visit_faqreflist_node, depart_faqreflist_node),
201 text=(visit_faqreflist_node, depart_faqreflist_node),
202 md=(visit_faqreflist_node, depart_faqreflist_node),
203 rst=(visit_faqreflist_node, depart_faqreflist_node))
204 app.add_node(faqref_node,
205 html=(visit_faqref_node, depart_faqref_node),
206 epub=(visit_faqref_node, depart_faqref_node),
207 elatex=(visit_faqref_node, depart_faqref_node),
208 latex=(visit_faqref_node, depart_faqref_node),
209 text=(visit_faqref_node, depart_faqref_node),
210 md=(visit_faqref_node, depart_faqref_node),
211 rst=(visit_faqref_node, depart_faqref_node))
213 app.add_directive('faqref', FaqRef)
214 app.add_directive('faqreflist', FaqRefList)
215 app.connect('doctree-read', process_faqrefs)
216 app.connect('doctree-resolved', process_faqref_nodes)
217 app.connect('env-purge-doc', purge_faqrefs)
218 app.connect('env-merge-info', merge_faqref)
219 return {'version': sphinx.__display_version__, 'parallel_read_safe': True}