Debian Codegraph @

jenkins_jobs/sphinx/yaml.py

raw
1 # Copyright 2012 Hewlett-Packard Development Company, L.P.
2 #
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
6 #
7 # http://www.apache.org/licenses/LICENSE-2.0
8 #
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12 # License for the specific language governing permissions and limitations
13 # under the License.
14
15 # Most of this code originated in sphinx.domains.python and
16 # sphinx.ext.autodoc and has been only slightly adapted for use in
17 # subclasses here.
18
19 # :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
20 # :license: BSD, see LICENSE for details.
21
22 import re
23
24 from sphinx import addnodes
25
26 try:
27 from sphinx.domains.python._annotations import _pseudo_parse_arglist
28 except ImportError:
29 from sphinx.domains.python import _pseudo_parse_arglist
30 from sphinx.domains.python import PyFunction, PyXRefRole
31 from sphinx.ext.autodoc import Documenter
32 from sphinx.ext.autodoc import FunctionDocumenter
33 from sphinx.locale import _
34
35
36 yaml_sig_re = re.compile(r"yaml:\s*(.*)")
37
38
39 class PyYAMLFunction(PyFunction):
40 def handle_signature(self, sig, signode):
41 """Transform a Python signature into RST nodes.
42
43 Return (fully qualified name of the thing, classname if any).
44
45 If inside a class, the current class name is handled intelligently:
46 * it is stripped from the displayed name if present
47 * it is added to the full name (return value) if not present
48 """
49 name_prefix = None
50 name = sig
51 arglist = None
52 retann = None
53
54 # determine module and class name (if applicable), as well as full name
55 modname = self.options.get("module", self.env.temp_data.get("py:module"))
56 classname = self.env.temp_data.get("py:class")
57
58 fullname = name
59
60 signode["module"] = modname
61 signode["class"] = classname
62 signode["fullname"] = fullname
63
64 sig_prefix = self.get_signature_prefix(sig)
65 if sig_prefix:
66 signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
67
68 if name_prefix:
69 signode += addnodes.desc_addname(name_prefix, name_prefix)
70
71 anno = self.options.get("annotation")
72
73 signode += addnodes.desc_name(name, name)
74 if not arglist:
75 if self.needs_arglist():
76 # for callables, add an empty parameter list
77 signode += addnodes.desc_parameterlist()
78 if retann:
79 signode += addnodes.desc_returns(retann, retann)
80 if anno:
81 signode += addnodes.desc_annotation(" " + anno, " " + anno)
82 return fullname, name_prefix
83
84 _pseudo_parse_arglist(signode, arglist)
85 if retann:
86 signode += addnodes.desc_returns(retann, retann)
87 if anno:
88 signode += addnodes.desc_annotation(" " + anno, " " + anno)
89 return fullname, name_prefix
90
91 def get_index_text(self, modname, name_cls):
92 return _("%s (in module %s)") % (name_cls[0], modname)
93
94
95 class YAMLFunctionDocumenter(FunctionDocumenter):
96 priority = FunctionDocumenter.priority + 10
97 objtype = "yamlfunction"
98 directivetype = "yamlfunction"
99
100 @classmethod
101 def can_document_member(cls, member, membername, isattr, parent):
102 if not FunctionDocumenter.can_document_member(
103 member, membername, isattr, parent
104 ):
105 return False
106 if member.__doc__ is not None and yaml_sig_re.match(member.__doc__):
107 return True
108 return False
109
110 def _find_signature(self, encoding=None):
111 docstrings = Documenter.get_doc(self)
112 if len(docstrings) != 1:
113 return
114 doclines = docstrings[0]
115 setattr(self, "__new_doclines", doclines)
116 if not doclines:
117 return
118 # match first line of docstring against signature RE
119 match = yaml_sig_re.match(doclines[0])
120 if not match:
121 return
122 name = match.group(1)
123 # ok, now jump over remaining empty lines and set the remaining
124 # lines as the new doclines
125 i = 1
126 while i < len(doclines) and not doclines[i].strip():
127 i += 1
128 setattr(self, "__new_doclines", doclines[i:])
129 return name
130
131 def get_doc(self, encoding=None, ignore=1):
132 lines = getattr(self, "__new_doclines", None)
133 if lines is not None:
134 return [lines]
135 return Documenter.get_doc(self)
136
137 def format_signature(self):
138 result = self._find_signature()
139 self._name = result
140 return ""
141
142 def format_name(self):
143 return self._name
144
145
146 def setup(app):
147 app.add_autodocumenter(YAMLFunctionDocumenter)
148 app.add_directive_to_domain("py", "yamlfunction", PyYAMLFunction)
149 app.add_role_to_domain("py", "yamlfunction", PyXRefRole())