documenters¶

class ClassDocumenter(package_path: str)¶

Bases: MemberDocumenter

A basic class documenter.

>>> import uqbar.apis
>>> path = "uqbar.apis.documenters.ClassDocumenter"
>>> documenter = uqbar.apis.ClassDocumenter(path)
>>> documentation = str(documenter)
>>> print(documentation)
.. autoclass:: ClassDocumenter
   :members:
   :undoc-members:

Tip

Subclass ClassDocumenter to implement your own custom class documentation output. You’ll need to provide your desired reStructuredText output via an overridden __str__() implementation.

See SummarizingClassDocumenter for an example.

Parameters:¶

package_path: str¶

the module path and name of the member to document

classmethod validate_client(client: object, module_path: str) → bool¶

Check if the member documenter can document the provided client.

Parameters:¶

client: object¶

the potential client to validate

module_path: str¶

the package path of the module where the client was encountered

property documentation_section : str¶

class FunctionDocumenter(package_path: str)¶

Bases: MemberDocumenter

A basic function documenter.

>>> import uqbar.apis
>>> path = "uqbar.io.walk"
>>> documenter = uqbar.apis.FunctionDocumenter(path)
>>> documentation = str(documenter)
>>> print(documentation)
.. autofunction:: walk

Tip

Subclass FunctionDocumenter to implement your own custom module documentation output. You’ll need to provide your desired reStructuredText output via an overridden __str__() implementation.

Parameters:¶

package_path: str¶

the module path and name of the member to document

classmethod validate_client(client: object, module_path: str) → bool¶

Check if the member documenter can document the provided client.

Parameters:¶

client: object¶

the potential client to validate

module_path: str¶

the package path of the module where the client was encountered

property documentation_section : str¶

class MemberDocumenter(package_path: str)¶

Bases: object

Abstract base class for module member documenters.

Member documenters generate reStructuredText output for classes, functions and other objects defined in modules. They also implement the logic for identifying which of those objects should be selected for documenting via their validate_client() method. Module documenters loop over their client module’s dict and try each of their member documenter class’ validation method against each dict member in turn in order to identify documentable content and associate it with a member documenter class.

Tip

Subclass MemberDocumenter to implement your own custom module member documentation output. You’ll need to override validate_client() with custom identification logic, and provide your desired reStructuredText output via an overridden __str__() implementation.

Parameters:¶

package_path: str¶

the module path and name of the member to document

classmethod validate_client(client: object, module_path: str) → bool¶

Check if the member documenter can document the provided client.

Parameters:¶

client: object¶

the potential client to validate

module_path: str¶

the package path of the module where the client was encountered

property client : object¶

property documentation_section : str¶

property package_path : str¶

class ModuleDocumenter(package_path: str, document_private_members: bool = False, member_documenter_classes: Sequence[type[MemberDocumenter]] | None = None, module_documenters: Sequence[ModuleDocumenter] | None = None)¶

Bases: object

A basic module documenter.

>>> import uqbar.apis
>>> documenter = uqbar.apis.ModuleDocumenter("uqbar.io")
>>> print(str(documenter))
.. _uqbar--io:

io
==

.. automodule:: uqbar.io

.. currentmodule:: uqbar.io

.. autoclass:: DirectoryChange
   :members:
   :undoc-members:

.. autoclass:: Profiler
   :members:
   :undoc-members:

.. autoclass:: RedirectedStreams
   :members:
   :undoc-members:

.. autoclass:: Timer
   :members:
   :undoc-members:

.. autofunction:: find_common_prefix

.. autofunction:: find_executable

.. autofunction:: open_path

.. autofunction:: relative_to

.. autofunction:: walk

.. autofunction:: write

Tip

Subclass ModuleDocumenter to implement your own custom module documentation output. You’ll need to provide your desired reStructuredText output via an overridden __str__() implementation.

See SummarizingModuleDocumenter for an example.

Parameters:¶

package_path: str¶

the module path of the module to document

document_private_members: bool = False¶

whether to documenter private module members

member_documenter_classes: Sequence[type[MemberDocumenter]] | None = None¶

a list of MemberDocumenter subclasses, defining what classes to use to identify and document module members

module_documenters: Sequence[ModuleDocumenter] | None = None¶

a list of of documenters for submodules and subpackages of the documented module; these are generated by an APIBuilder instance rather than the module documenter directly

property client : object¶

property document_private_members : bool¶

property documentation_path : Path¶

property is_nominative : bool¶

property is_package : bool¶

property member_documenter_classes : Sequence[type[MemberDocumenter]]¶

property member_documenters : Sequence[MemberDocumenter]¶

property member_documenters_by_section : Sequence[tuple[str, Sequence[MemberDocumenter]]]¶

property module_documenters : Sequence[ModuleDocumenter]¶

property package_name : str¶

property package_path : str¶

property reference_name : str¶

class RootDocumenter(module_documenters=None, title='API')¶

Bases: object

A basic root documenter.

This documenter generates only one reStructuredText document: the root API index page, which contains information about all of the modules traversed by an APIBuilder.

Output is a basic toctree directive.

>>> import uqbar.apis
>>> documenter = uqbar.apis.RootDocumenter(
...     module_documenters=[
...         uqbar.apis.ModuleDocumenter("uqbar.io"),
...         uqbar.apis.ModuleDocumenter("uqbar.strings"),
...     ],
... )
>>> print(str(documenter))
API
===

.. toctree::

   uqbar/io
   uqbar/strings

Tip

Subclass RootDocumenter to implement your own custom module documentation output. You’ll need to provide your desired reStructuredText output via an overridden __str__() implementation.

See SummarizingRootDocumenter for an example.

Parameters:¶

module_documenters=None¶

a list of of documenters for modules and packages of the root documenter; these are generated by an APIBuilder instance rather than the module documenter directly

property documentation_path¶

property module_documenters¶

property title¶