Add custom role for the cross references.

1  """
2  This module defines several customized directives or roles for the
3  documents written and processed at Logilab.
4  """
5 -from docutils import nodes
6 +from docutils import nodes, utils
7  from docutils.parsers.rst.directives import register_directive
8 +from docutils.parsers.rst.roles import register_canonical_role, set_classes
9  from docutils.parsers.rst import Directive
10  from docutils.parsers.rst.directives.admonitions import BaseAdmonition
11 
12 
13 -class PassDirective(Directive):
14 -    """
15 -    Directive that does nothing.
16 -    """
17 -    required_arguments = 0
18 -    optional_arguments = 0
19 -    has_content= True
20 -    def run(self):
21 -        return []
22 -
23 +### New Directive for the paragraphs preceded by a page break
24 
25  class BreakPara(Directive):
26      """
27      New directive describing a paragraph preceded by a page break.
28 

29 
30  # Registers the new directive class in the analyzer
31  register_directive('break-para', BreakPara)
32 
33 
34 +### New Directive for the draft notes
35 +
36  class draft(nodes.Admonition, nodes.Element):
37      """
38      New type of node that can be found inside the tree returned by the parser.
39 
40      The visitors must implement a enter / depart method for this node.

41 
42  # Registers the new directive class in the analyzer
43  register_directive('draft', Draft)
44 
45 
46 +### New directives for elements that must be ignored.
47 +
48 +class PassDirective(Directive):
49 +    """
50 +    Directive that does nothing.
51 +    """
52 +    required_arguments = 0
53 +    optional_arguments = 0
54 +    has_content= True
55 +    def run(self):
56 +        return []
57 +
58  # Registers the Sphinx-specific directive "toctree" in the analyzer
59  # As we don't use it, just does nothing when finding it.
60 -
61  register_directive('toctree', PassDirective)
62 
63 +
64 +### New text role for the cross references
65 +
66 +class crossref(nodes.Inline, nodes.TextElement):
67 +    """
68 +    New type of node that can be found inside the tree returned by the parser.
69 +
70 +    The visitors must implement a enter / depart method for this node.
71 +    """
72 +    pass
73 +
74 +def build_crossref_role(role, rawtext, text, lineno, inliner,
75 +                  options={}, content=[]):
76 +    set_classes(options)
77 +    return [crossref(rawtext, "", refid=utils.unescape(text),
78 +                     **options)], []
79 +
80 +register_canonical_role('crossref', build_crossref_role)

81 
82 
83      def visit_generated(self, node):
84          # The generated node are only used to insert the section
85          # numbers that are automatically computed by ReST.
86 -        # In DocBook, we don't need to numbre the sections as they will
87 -        # be autmatically numbered.
88 +        # In DocBook, we don't need to number the sections as they will
89 +        # be automatically numbered.
90          raise SkipNode
91 
92      def depart_generated(self, node):
93          pass
94 

95          self.parents_stack.append(elt)
96 
97      def depart_warning(self, node):
98          self.parents_stack.pop()
99 
100 +    ### Custom nodes (cf. custom module)
101 +
102 +    def visit_crossref(self, node):
103 +        elt = SubElement(self.parents_stack[-1], u"xref",
104 +                         linkend=node.get('refid', ''))
105 +        self.insert_ids(node, elt)
106 +        self.insert_classes(node, elt)
107 +        self.parents_stack.append(elt)
108 +
109 +    def depart_crossref(self, node):
110 +        self.parents_stack.pop()
111 +
112      def visit_draft(self, node):
113          elt = SubElement(self.parents_stack[-1], u"{%s}draft" % LDG_NS)
114          self.insert_ids(node, elt)
115          self.insert_classes(node, elt)
116          self.parents_stack.append(elt)
117 
118      def depart_draft(self, node):
119          self.parents_stack.pop()
120 -
121 -