Coverage for pyquickhelper/sphinxext/sphinx_gitlog_extension.py: 90%
48 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 display gitlog text.
5"""
6from datetime import datetime
7import sphinx
8from docutils import nodes
9from sphinx.util.logging import getLogger
12class gitlog_node(nodes.Element):
14 """
15 Defines *gitlog* node.
16 """
17 pass
20def gitlog_role(role, rawtext, text, lineno, inliner, options=None, content=None):
21 """
22 Defines custom role *gitlog*. The following instruction prints
23 out the date of the last modification for the current file.
25 ::
27 :gitlog:`date`
29 :param role: The role name used in the document.
30 :param rawtext: The entire markup snippet, with role.
31 :param text: The text marked with the role.
32 :param lineno: The line number where rawtext appears in the input.
33 :param inliner: The inliner instance that called us.
34 :param options: Directive options for customization.
35 :param content: The directive content for customization.
36 """
37 if options is None:
38 options = {}
39 if content is None:
40 content = []
41 node = gitlog_node(text=text)
42 node['classes'] += ["gitlog"]
43 if text == 'date':
44 source = inliner.document.current_source
45 if source == '<string>':
46 value = str(datetime.now())
47 else:
48 from ..loghelper.repositories.pygit_helper import get_file_last_modification
49 value = get_file_last_modification(source)
50 node['text'] = value
51 elif text.startswith('date:'):
52 source = text[5:]
53 from ..loghelper.repositories.pygit_helper import get_file_last_modification
54 value = get_file_last_modification(source)
55 node['text'] = value
56 else:
57 raise ValueError( # pragma: no cover
58 f"Unable to interpret this instuction '{text}'.")
59 return [node], []
62def depart_gitlog_node_html(self, node):
63 """
64 what to do when leaving a node *gitlog*
65 the function should have different behaviour,
66 depending on the format, or the setup should
67 specify a different function for each.
69 It does only html for the time being.
70 """
71 self.body.append(node["text"])
74def visit_gitlog_node_rst(self, node):
75 """
76 what to do when visiting a node *gitlog*
77 the function should have different behaviour,
78 depending on the format, or the setup should
79 specify a different function for each.
80 """
81 self.add_text(':gitlog:`')
82 self.add_text(node["text"])
85def depart_gitlog_node_rst(self, node):
86 """
87 depart *gitlog_node* for rst
88 """
89 self.add_text('`')
92def visit_gitlog_node_latex(self, node):
93 """
94 what to do when visiting a node *gitlog*
95 the function should have different behaviour,
96 depending on the format, or the setup should
97 specify a different function for each.
98 """
99 self.add_text(node["text"])
102def depart_gitlog_node_latex(self, node):
103 """
104 depart *gitlog_node* for latex
105 """
108def visit_gitlog_node(self, node):
109 """
110 what to do when visiting a node *gitlog*
111 the function should have different behaviour,
112 depending on the format, or the setup should
113 specify a different function for each.
114 """
115 pass
118def depart_gitlog_node(self, node):
119 """
120 depart *gitlog_node* for format other than html
121 """
122 logger = getLogger("gitlog")
123 logger.warning(
124 "[depart_gitlog_node] output only available for HTML not for %r", type(self))
127def setup(app):
128 """
129 setup for ``gitlog`` (sphinx)
130 """
131 if hasattr(app, "add_mapping"):
132 app.add_mapping('gitlog', gitlog_node)
134 app.add_node(gitlog_node,
135 html=(visit_gitlog_node, depart_gitlog_node_html),
136 epub=(visit_gitlog_node, depart_gitlog_node_html),
137 latex=(visit_gitlog_node_latex, depart_gitlog_node_latex),
138 elatex=(visit_gitlog_node_latex, depart_gitlog_node_latex),
139 text=(visit_gitlog_node, depart_gitlog_node),
140 md=(visit_gitlog_node, depart_gitlog_node),
141 rst=(visit_gitlog_node_rst, depart_gitlog_node_rst))
143 app.add_role('gitlog', gitlog_role)
144 return {'version': sphinx.__display_version__, 'parallel_read_safe': True}