more_autodoc.autoprotocol
¶
A Sphinx directive for documenting Protocols
in Python.
New in version 0.2.0.
Enable sphinx_toolbox.more_autodoc.autoprotocol
by adding the following
to the extensions
variable in your conf.py
:
extensions = [
...
'sphinx_toolbox.more_autodoc.autoprotocol',
]
For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .
Changed in version 0.6.0: Moved from sphinx_toolbox.autoprotocol
.
Changed in version 2.13.0: Added support for generic bases, such as class SupportsAbs(Protocol[T_co]): ...
.
Usage¶
-
.. autoprotocol::
¶ Directive to automatically document a
typing.Protocol
.The output is based on the
autoclass
directive, but with a few differences:Private members are always excluded.
Special members (dunder methods) are always included.
Undocumented members are always included.
The following options from
autoclass
are available:-
:noindex:
(flag)¶ Do not generate index entries for the documented object (and all autodocumented members).
-
:member-order:
(string)¶ Override the global value of
autodoc_member_order
for one directive.
-
:show-inheritance:
(flag)¶ Inserts a list of base classes just below the protocol’s signature.
-
:protocol:
¶ Role which provides a cross-reference to the documentation generated by
autoprotocol
.
Examples:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | # stdlib from abc import abstractmethod from typing import Any, TypeVar # 3rd party from domdf_python_tools.doctools import prettify_docstrings from typing_extensions import Protocol, runtime_checkable __all__ = ("HasLessThan", "HasGreaterThan", "Frobnicater") @prettify_docstrings class HasLessThan(Protocol): """ :class:`typing.Protocol` for classes that support the ``<`` operator. """ def __lt__(self, other) -> bool: ... @prettify_docstrings class HasGreaterThan(Protocol): def __gt__(self, other) -> bool: ... @runtime_checkable class Frobnicater(Protocol): def frobnicate(self, something) -> Any: ... |
.. automodule:: autoprotocol_demo
:members:
:no-autosummary:
:exclude-members: HasGreaterThan
.. autoprotocol:: autoprotocol_demo.HasGreaterThan
The objects being sorted must implement the :protocol:`~.HasGreaterThan` protocol.
-
protocol
Frobnicater
[source]¶ Bases:
Protocol
This protocol is runtime checkable.
Classes that implement this protocol must have the following methods / attributes:
-
protocol
HasLessThan
[source]¶ Bases:
Protocol
typing.Protocol
for classes that support the<
operator.Classes that implement this protocol must have the following methods / attributes:
-
protocol
HasGreaterThan
[source]¶ Bases:
Protocol
Classes that implement this protocol must have the following methods / attributes:
The objects being sorted must implement the HasGreaterThan
protocol.
API Reference¶
Classes:
|
Sphinx autodoc |
Functions:
|
-
class
ProtocolDocumenter
(directive, name, indent='')[source]¶ Bases:
ClassDocumenter
Sphinx autodoc
Documenter
for documentingtyping.Protocol
s.Methods:
add_content
(more_content[, no_docstring])Add the autodocumenter content.
add_directive_header
(sig)Add the directive header.
can_document_member
(member, membername, …)Called to see if a member can be documented by this documenter.
document_members
([all_members])Generate reST for member documentation.
filter_members
(members, want_all)Filter the given member list.
format_signature
(**kwargs)Protocols do not have a signature.
-
classmethod
can_document_member
(member, membername, isattr, parent)[source]¶ Called to see if a member can be documented by this documenter.
-
document_members
(all_members=False)[source]¶ Generate reST for member documentation.
All members are always documented.
-
classmethod
-
setup
(app)[source]¶ Setup
sphinx_toolbox.more_autodoc.autoprotocol
.- Parameters
app (
Sphinx
) – The Sphinx application.- Return type