pydocspec

package documentation

(source)

Pydocspec is a object specification for representing API documentation of a collection of related python modules. It offers facility to resolve names according to python lookups rules and provides additional informations.

Warning:

Work in progress... API might change without deprecation notice.

Usage:

>>> import pydocspec
>>> root = pydocspec.load_python_modules([Path('./pydocspec')])

How it works

First, a root object gets created with the specfactory, then the astbuilder creates all the other objects and populate the strict-minimum attributes. Then the processor takes that tree and populated all other attributes.

Extensibility:

The core of the logic is design to be extensible with extensions modules. See pydocspec.ext.

Module	`astbuilder`	Traverse module/packages directories, build and transform `astroid` AST into `ApiObject` instances.
Module	`astroidutils`	Various bits of reusable code related to `astroid.nodes.NodeNG` node processing.
Module	`basebuilder`	No module docstring; 0/2 variable, 1/1 function, 1/5 class documented
Module	`converter`	Convert `docspec` objects to their `pydocspec` augmented version.
Module	`dottedname`	No module docstring; 3/3 functions, 1/1 class documented
Module	`dupsafedict`	No module docstring; 0/2 constant, 1/1 class documented
Package	`ext`	Extensions sytem.
Module	`genericvisitor`	General purpose visitor pattern implementation, with extensions.
Package	`processor`	Processes the half baked model created by the builder to populate buch of fancy attributes.
Module	`specfactory`	Create customizable docspec classes.
Package	`test`	Undocumented
Module	`tmp`	Undocumented
Module	`visitors`	Useful visitors for AST and `pydocspec.ApiObject` instances.
Module	`__main__`	Undocumented
Module	`_c3linear`	Compute method resolution order. Implements `Class.mro` attribute.
Module	`_docspec`	Mirrors `docspec` model, but without using `dataclasses` (and without deprecated attributes).
Module	`_model`	Like the `docspec` classes, but with ast attributes and few goodies added such that efficient processing can be done on these objects afterwards.

From __init__.py:

Class	`ApiObject`	An augmented `docspec.ApiObject`, with functionalities to resolve names for the python language.
Class	`Class`	Represents a class definition.
Class	`ClassInheritedMember`	Undocumented
Class	`Function`	Represents a function definition.
Class	`Indirection`	Represents an imported name. It can be used to properly find the full name target of a link written with a local name.
Class	`Module`	Represents a module, basically a named container for code/API objects. Modules may be nested in other modules
Class	`Options`	Undocumented
Class	`TreeRoot`	A collection of related documentable objects, also known as "the system".
Class	`Variable`	Represents a variable assignment.
Function	`builder_from_options`	Factory method for Builder instances.
Function	`load_python_modules`	Load packages or modules with pydocspec's builder.
Function	`load_python_modules_with_docspec_python`	Load packages or modules with docspec_python and then convert them to pydocspec objects.
Function	`_setup_stdout_logger`	Utility to create a logger.
Constant	`_RESOLVE_ALIAS_MAX_RECURSE`	Undocumented

_RESOLVE_ALIAS_MAX_RECURSE: int = (source)

Undocumented

Value

def builder_from_options(options=None): (source)

Factory method for Builder instances.

This function puts together everything we need to build object trees with extensions.

Parameters
options:`Optional[Options]`	Undocumented
Returns
`astbuilder.Builder`	Undocumented

def load_python_modules(files, options=None): (source)

Load packages or modules with pydocspec's builder.

Parameters
files:`Sequence[Path]`	A list of `Path` instances pointing to filenames/directory to parse. Directories will be added recursively.
options:`Optional[Options]`	Undocumented
Returns
`TreeRoot`	Undocumented

def load_python_modules_with_docspec_python(files, options=None, docspec_options=None): (source)

Load packages or modules with docspec_python and then convert them to pydocspec objects.

Parameters
files:`Sequence[Path]`	Undocumented
options:`Optional[Options]`	Undocumented
docspec_options:`docspec_python.ParserOptions`	Undocumented
Returns
`TreeRoot`	Undocumented

def _setup_stdout_logger(name, verbose=False, quiet=False): (source)

Utility to create a logger.

Parameters
name:`str`	Undocumented
verbose:`bool`	Undocumented
quiet:`bool`	Undocumented
Returns
`logging.Logger`	Undocumented