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

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

2""" 

3@file 

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

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

13 """ 

14 defines ``faqref`` ndoe 

15 """ 

16 pass 

17 

18 

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

20 """ 

21 defines ``faqreflist`` node 

22 """ 

23 pass 

24 

25 

26class FaqRef(BlocRef): 

27 """ 

28 A ``faqref`` 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 .. faqref:: 

39 :title: example of a blocref 

40 :lid: id-you-can-choose 

41 

42 An example of code: 

43 

44 :: 

45 

46 print("mignon") 

47 

48 Which renders as: 

49 

50 .. faqref:: 

51 :title: example of a faqref 

52 :tag: dummy_example2 

53 :lid: id-you-can-choose2 

54 

55 An example of code: 

56 

57 :: 

58 

59 print("mignon") 

60 

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

62 

63 .. faqreflist:: 

64 :tag: dummy_example2 

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 .. faqreflist:: 

73 :tag: dummy_example2 

74 :sort: title 

75 """ 

76 

77 node_class = faqref_node 

78 name_sphinx = "faqref" 

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"] = "faq" 

86 return BlocRef.run(self) 

87 

88 

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) 

97 

98 

99class FaqRefList(BlocRefList): 

100 """ 

101 A list of all *faqref* 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 .. faqreflist:: 

110 :tag: issue 

111 :contents: 

112 """ 

113 name_sphinx = "faqreflist" 

114 node_class = faqreflist 

115 

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) 

123 

124 

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) 

132 

133 

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] 

142 

143 

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) 

153 

154 

155def visit_faqref_node(self, node): 

156 """ 

157 visit_faqref_node 

158 """ 

159 self.visit_admonition(node) 

160 

161 

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) 

168 

169 

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) 

176 

177 

178def depart_faqreflist_node(self, node): 

179 """ 

180 depart_faqref_node 

181 """ 

182 self.depart_admonition(node) 

183 

184 

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) 

192 

193 app.add_config_value('faqref_include_faqrefs', True, 'html') 

194 app.add_config_value('faqref_link_only', False, 'html') 

195 

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)) 

212 

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}