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