""" ======== briandoc ======== Sphinx extension that handles docstrings in the Numpy standard format with some brian-specific tweaks. [1] It will: - Convert Parameters etc. sections to field lists. - Convert See Also section to a See also entry. - Renumber references. - Extract the signature from the docstring, if it can't be determined otherwise. .. [1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt """ import inspect import pydoc import re from docutils import nodes, statemachine from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList from sphinx.domains.c import CDomain from sphinx.domains.python import PythonDomain, PyXRefRole from sphinx.roles import XRefRole from brian2.core.preferences import prefs from .docscrape_sphinx import SphinxDocString, get_doc_object class BrianPrefsDirective(Directive): """ A sphinx 'Directive' for automatically generated documentation of Brian preferences. The directive takes an optional argument, the basename of the preferences to document. In addition, you can specify a `nolinks` option which means that no target links for the references are added. Do this if you document preferences in more then one place. Examples -------- Document one category of preferences and generate links:: .. document_brian_prefs:: core Document all preferences without generating links:: .. document_brian_prefs:: :nolinks: """ required_arguments = 0 optional_arguments = 1 final_argument_whitespace = True option_spec = {"nolinks": directives.flag, "as_file": directives.flag} has_content = False def run(self): # The section that should be documented if len(self.arguments): section = self.arguments[0] else: section = None if "as_file" in self.options: rawtext = prefs.as_file return [nodes.literal_block(text=rawtext)] else: rawtext = prefs.get_documentation(section, "nolinks" not in self.options) include_lines = statemachine.string2lines(rawtext, convert_whitespace=True) self.state_machine.insert_input(include_lines, "Brian preferences") return [] def brianobj_role(role, rawtext, text, lineno, inliner, options=None, content=None): """ A Sphinx role, used as a wrapper for the default `py:obj` role, allowing us to use the simple backtick syntax for brian classes/functions without having to qualify the package for classes/functions that are available after a `from brian2 import *`, e.g `NeuronGroup`. Also allows to directly link to preference names using the same syntax. """ if options is None: options = {} if content is None: content = [] if text in prefs: linktext = text.replace("_", "-").replace(".", "-") text = f"{text} " # Use sphinx's cross-reference role xref = XRefRole(warn_dangling=True) return xref("std:ref", rawtext, text, lineno, inliner, options, content) else: if text and ("~" not in text): try: # A simple class or function name if "." not in text: module = __import__("brian2", fromlist=[str(text)]) imported = getattr(module, str(text), None) if getattr(imported, "__module__", None): text = f"~{imported.__module__}.{text}" if inspect.isfunction(imported): text += "()" # Possibly a method/classmethod/attribute name elif len(text.split(".")) == 2: classname, attrname = text.split(".") # Remove trailing parentheses (will be readded for display) if attrname.endswith("()"): attrname = attrname[:-2] module = __import__("brian2", fromlist=[str(classname)]) imported = getattr(module, str(classname), None) if hasattr(imported, "__module__"): # Add trailing parentheses only for methods not for # attributes if inspect.ismethod(getattr(imported, str(attrname), None)): parentheses = "()" else: parentheses = "" text = ( f"{classname}.{attrname}{parentheses} " f"<{imported.__module__}.{classname}.{attrname}>" ) except ImportError: pass role = "py:obj" py_role = PyXRefRole() return py_role(role, rawtext, text, lineno, inliner, options, content) def mangle_docstrings(app, what, name, obj, options, lines, reference_offset=None): if reference_offset is None: reference_offset = [0] cfg = dict() if what == "module": # Strip top title title_re = re.compile(r"^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*", re.I | re.S) lines[:] = title_re.sub("", "\n".join(lines)).split("\n") exported_members = getattr(obj, "__all__", None) if exported_members: lines.append("*Exported members:* ") exported_members = sorted(exported_members) # do not print more than 25 members lines.append(", ".join([f"`{member}`" for member in exported_members[:25]])) if len(exported_members) > 25: lines.append(f"... ({int(len(exported_members) - 25)} more members)") lines.append("") else: doc = get_doc_object(obj, what, "\n".join(lines), name=name, config=cfg) lines[:] = str(doc).split("\n") # replace reference numbers so that there are no duplicates references = [] for line in lines: line = line.strip() m = re.match(r"^.. \[([a-z0-9_.-])\]", line, re.I) if m: references.append(m.group(1)) # start renaming from the longest string, to avoid overwriting parts references.sort(key=lambda x: -len(x)) if references: for i in range(len(lines)): for r in references: if re.match(r"^\d+$", r): new_r = f"R{int(reference_offset[0] + int(r))}" else: new_r = f"{r}{int(reference_offset[0])}" lines[i] = lines[i].replace(f"[{r}]_", f"[{new_r}]_") lines[i] = lines[i].replace(f".. [{r}]", f".. [{new_r}]") reference_offset[0] += len(references) def mangle_signature(app, what, name, obj, options, sig, retann): # Do not try to inspect classes that don't define `__init__` if inspect.isclass(obj) and ( not hasattr(obj, "__init__") or "initializes x; see " in pydoc.getdoc(obj.__init__) ): return "", "" if not (callable(obj) or hasattr(obj, "__argspec_is_invalid_")): return if not hasattr(obj, "__doc__"): return doc = SphinxDocString(pydoc.getdoc(obj)) if doc["Signature"]: sig = re.sub("^[^(]*", "", doc["Signature"]) return sig, "" def setup(app, get_doc_object_=get_doc_object): global get_doc_object get_doc_object = get_doc_object_ app.connect("autodoc-process-docstring", mangle_docstrings) app.connect("autodoc-process-signature", mangle_signature) # Extra mangling domains app.add_domain(NumpyPythonDomain) app.add_domain(NumpyCDomain) directives.register_directive("document_brian_prefs", BrianPrefsDirective) # provide the brianobj role with a link to the Python domain app.add_role("brianobj", brianobj_role) # ------------------------------------------------------------------------------ # Docstring-mangling domains # ------------------------------------------------------------------------------ class ManglingDomainBase: directive_mangling_map = {} def __init__(self, *a, **kw): super().__init__(*a, **kw) self.wrap_mangling_directives() def wrap_mangling_directives(self): for name, objtype in self.directive_mangling_map.items(): self.directives[name] = wrap_mangling_directive( self.directives[name], objtype ) class NumpyPythonDomain(ManglingDomainBase, PythonDomain): name = "np" directive_mangling_map = { "function": "function", "class": "class", "exception": "class", "method": "function", "classmethod": "function", "staticmethod": "function", "attribute": "attribute", } class NumpyCDomain(ManglingDomainBase, CDomain): name = "np-c" directive_mangling_map = { "function": "function", "member": "attribute", "macro": "function", "type": "class", "var": "object", } def wrap_mangling_directive(base_directive, objtype): class directive(base_directive): def run(self): env = self.state.document.settings.env name = None if self.arguments: m = re.match(r"^(.*\s+)?(.*?)(\(.*)?", self.arguments[0]) name = m.group(2).strip() if not name: name = self.arguments[0] lines = list(self.content) mangle_docstrings(env.app, objtype, name, None, None, lines) self.content = ViewList(lines, self.content.parent) return base_directive.run(self) return directive