module sphinxext.sphinx_autosignature

Inheritance diagram of pyquickhelper.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 node at the root 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)[source]

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[source]

alias of autosignature_node

build_members(obj, members, object_name, annotation, summary)[source]

Extracts methods of a class and document them.

source on GitHub

build_parameters_list(parameters, annotation)[source]

Builds the list of parameters.

Parameters
  • parameters – list of Parameters

  • annotation – add annotation

Returns

string (RST format)

source on GitHub

build_summary(docstring)[source]

Extracts the part of the docstring before the parameters.

Parameters

docstring – document string

Returns

string

source on GitHub

final_argument_whitespace = True[source]

May the final argument contain whitespace?

has_content = True[source]

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>}[source]

Mapping of option names to validator functions.

optional_arguments = 0[source]

Number of optional arguments after the required arguments.

static reformat(text, indent=4)[source]

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[source]

Number of required directive arguments.

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

Bases: Structural, Element

Defines autosignature node.

source on GitHub

__slotnames__ = [][source]
pyquickhelper.sphinxext.sphinx_autosignature.depart_autosignature_node(self, node)[source]

What to do when leaving a node autosignature_node.

source on GitHub

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

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)[source]

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)[source]

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)[source]

What to do when visiting a node autosignature_node.

source on GitHub