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 

10 

11 

12class gitlog_node(nodes.Element): 

13 

14 """ 

15 Defines *gitlog* node. 

16 """ 

17 pass 

18 

19 

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. 

24 

25 :: 

26 

27 :gitlog:`date` 

28 

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 "Unable to interpret this instuction '{}'.".format(text)) 

59 return [node], [] 

60 

61 

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. 

68 

69 It does only html for the time being. 

70 """ 

71 self.body.append(node["text"]) 

72 

73 

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

83 

84 

85def depart_gitlog_node_rst(self, node): 

86 """ 

87 depart *gitlog_node* for rst 

88 """ 

89 self.add_text('`') 

90 

91 

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

100 

101 

102def depart_gitlog_node_latex(self, node): 

103 """ 

104 depart *gitlog_node* for latex 

105 """ 

106 

107 

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 

116 

117 

118def depart_gitlog_node(self, node): 

119 """ 

120 depart *gitlog_node* for format other than html 

121 """ 

122 logger = getLogger("gitlog") 

123 logger.warning("[depart_gitlog_node] output only available for HTML not for '{0}'".format( 

124 type(self))) 

125 

126 

127def setup(app): 

128 """ 

129 setup for ``gitlog`` (sphinx) 

130 """ 

131 if hasattr(app, "add_mapping"): 

132 app.add_mapping('gitlog', gitlog_node) 

133 

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

142 

143 app.add_role('gitlog', gitlog_role) 

144 return {'version': sphinx.__display_version__, 'parallel_read_safe': True}