module sphinxext.sphinx_autosignature

Short summary

module pyquickhelper.sphinxext.sphinx_autosignature

Defines a sphinx extension to describe a function, inspired from autofunction and AutoDirective.

source on GitHub

Classes

class	truncated documentation
autosignature_node	Defines autosignature node.
AutoSignatureDirective	This directive displays a shorter signature than sphinx.ext.autodoc. Available options:

Functions

function	truncated documentation
depart_autosignature_node	What to do when leaving a node autosignature_node.
enumerate_cleaned_signature	Removes annotation from a signature extracted with enumerate_extract_signature().
enumerate_extract_signature	Looks for substring like the following and clean the signature to be able to use function _signature_fromstr.
setup	Create a new directive called autosignature which displays the signature of the function.
visit_autosignature_node	What to do when visiting a node autosignature_node.

Properties

property	truncated documentation
document	Return the document root node of the tree containing this Node.

Static Methods

staticmethod	truncated documentation
reformat	Formats the number of spaces in front every line to be equal to a specific value.

Methods

method	truncated documentation
build_members	Extracts methods of a class and document them.
build_parameters_list	Builds the list of parameters.
build_summary	Extracts the part of the docstring before the parameters.
run

Documentation

Defines a sphinx extension to describe a function, inspired from autofunction and AutoDirective.

source on GitHub

class pyquickhelper.sphinxext.sphinx_autosignature.AutoSignatureDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Directive

This directive displays a shorter signature than sphinx.ext.autodoc. Available options:

• nosummary: do not display a summary (shorten)

• annotation: shows annotation

• nolink: if False, add a link to a full documentation (produced by sphinx.ext.autodoc)

• members: shows members of a class

• path: three options, full displays the full path including submodules, name displays the last name, import displays the shortest syntax to import it (default).

• debug: diplays debug information

• syspath: additional paths to add to sys.path before importing, ‘;’ separated list

The signature is not always available for builtin functions or C++ functions depending on the way to bind them to Python. See Set the __text_signature__ attribute of callables.

The signature may not be infered by module inspect if the function is a compiled C function. In that case, the signature must be added to the documentation. It will parsed by autosignature with by function enumerate_extract_signature with regular expressions.

source on GitHub

autosignature_class

alias of autosignature_node

build_members(obj, members, object_name, annotation, summary)

Extracts methods of a class and document them.

source on GitHub

build_parameters_list(parameters, annotation)

Builds the list of parameters.

Parameters:

• parameters – list of Parameters

• annotation – add annotation

Returns:

string (RST format)

source on GitHub

build_summary(docstring)

Extracts the part of the docstring before the parameters.

Parameters:

docstring – document string

Returns:

string

source on GitHub

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = True

May the directive have content?

option_spec = {'annotation': <function unchanged>, 'debug': <function unchanged>, 'members': <function unchanged>, 'nolink': <function unchanged>, 'nosummary': <function unchanged>, 'path': <function unchanged>, 'syspath': <function unchanged>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

static reformat(text, indent=4)

Formats the number of spaces in front every line to be equal to a specific value.

Parameters:

• text – text to analyse

• indent – specify the expected indentation for the result

Returns:

number

source on GitHub

required_arguments = 0

Number of required directive arguments.

class pyquickhelper.sphinxext.sphinx_autosignature.autosignature_node(rawsource='', *children, **attributes)

Bases: Structural, Element

Defines autosignature node.

source on GitHub

__slotnames__ = []

pyquickhelper.sphinxext.sphinx_autosignature.depart_autosignature_node(self, node)

What to do when leaving a node autosignature_node.

source on GitHub

pyquickhelper.sphinxext.sphinx_autosignature.enumerate_cleaned_signature(doc, max_args=20)

Removes annotation from a signature extracted with enumerate_extract_signature.

Parameters:

• doc – text to parse

• max_args – maximum number of parameters

Returns:

iterator of found signatures

source on GitHub

pyquickhelper.sphinxext.sphinx_autosignature.enumerate_extract_signature(doc, max_args=20)

Looks for substring like the following and clean the signature to be able to use function _signature_fromstr.

Parameters:

• doc – text to parse

• max_args – maximum number of parameters

Returns:

iterator of found signatures

__init__(self: cpyquickhelper.numbers.weighted_number.WeightedDouble,
         value: float, weight: float=1.0) -> None

It is limited to 20 parameters.

source on GitHub

pyquickhelper.sphinxext.sphinx_autosignature.setup(app)

Create a new directive called autosignature which displays the signature of the function.

source on GitHub

pyquickhelper.sphinxext.sphinx_autosignature.visit_autosignature_node(self, node)

What to do when visiting a node autosignature_node.

source on GitHub