more_autodoc.autonamedtuple
¶
A Sphinx directive for documenting NamedTuples
in Python.
New in version 0.8.0.
Enable sphinx_toolbox.more_autodoc.autonamedtuple
by adding the following
to the extensions
variable in your conf.py
:
extensions = [
...
'sphinx_toolbox.more_autodoc.autonamedtuple',
]
For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .
Changed in version 1.5.0: __new__
methods are documented regardless of other exclusion settings
if the annotations differ from the namedtuple itself.
Usage¶
-
.. autonamedtuple::
¶ Directive to automatically document a
typing.NamedTuple
orcollections.namedtuple()
.The output is based on the
autoclass
directive. The list of parameters and the attributes are replaced by a list of Fields, combining the types and docstrings from the class docstring individual attributes. These will always be shown regardless of the state of the:members:
option.Otherwise the directive behaves the same as
autoclass
, and takes all of its arguments. See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html for further information.New in version 0.8.0.
-
:namedtuple:
¶ Role which provides a cross-reference to the documentation generated by
autonamedtuple
.
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 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | # Examples from # https://docs.python.org/3/library/typing.html#typing.NamedTuple # https://www.python.org/dev/peps/pep-0589/#totality # https://github.com/python/typing/pull/700 # stdlib import collections from typing import NamedTuple __all__ = ["Animal", "Employee", "Movie"] class Animal(NamedTuple): """ An animal. :param name: The name of the animal. :param voice: The animal's voice. """ name: str voice: str class Employee(NamedTuple): """ Represents an employee. :param id: The employee's ID number """ #: The employee's name name: str id: int = 3 def __repr__(self) -> str: return f'<Employee {self.name}, id={self.id}>' def is_executive(self) -> bool: """ Returns whether the employee is an executive. Executives have ID numbers < 10. """ class Movie(NamedTuple): """ Represents a movie. """ #: The name of the movie. name: str #: The movie's release year. year: int based_on: str |
.. automodule:: autonamedtuple_demo
:no-autosummary:
:exclude-members: Movie
.. autonamedtuple:: autonamedtuple_demo.Movie
This function takes a single argument, the :namedtuple:`~.Movie` to watch.
-
namedtuple
Animal
(name, voice)[source]¶ Bases:
NamedTuple
An animal.
-
__repr__
()¶ Return a nicely formatted representation string
-
-
namedtuple
Employee
(name, id=3)[source]¶ Bases:
NamedTuple
Represents an employee.
-
namedtuple
Movie
(name, year, based_on)[source]¶ Bases:
NamedTuple
Represents a movie.
- Fields
-
__repr__
()¶ Return a nicely formatted representation string
This function takes a single argument, the Movie
to watch.
API Reference¶
Classes:
|
Sphinx autodoc |
Functions:
|
-
class
NamedTupleDocumenter
(directive, name, indent='')[source]¶ Bases:
ClassDocumenter
Sphinx autodoc
Documenter
for documentingtyping.NamedTuple
s.New in version 0.8.0.
Changed in version 0.1.0: Will no longer attempt to find attribute docstrings from other namedtuple classes.
Methods:
add_content
(more_content[, no_docstring])Add extra content (from docstrings, attribute docs etc.), but not the
typing.NamedTuple
's docstring.add_directive_header
(sig)Add the directive’s header, and the inheritance information if the
:show-inheritance:
flag set.can_document_member
(member, membername, …)Called to see if a member can be documented by this documenter.
filter_members
(members, want_all)Filter the list of members to always include
__new__
if it has a different signature to the tuple.sort_members
(documenters, order)Sort the
typing.NamedTuple
's members.-
add_content
(more_content, no_docstring=True)[source]¶ Add extra content (from docstrings, attribute docs etc.), but not the
typing.NamedTuple
's docstring.
-
add_directive_header
(sig)[source]¶ Add the directive’s header, and the inheritance information if the
:show-inheritance:
flag set.- Parameters
sig (
str
) – The NamedTuple’s signature.
-
classmethod
can_document_member
(member, membername, isattr, parent)[source]¶ Called to see if a member can be documented by this documenter.
-
-
setup
(app)[source]¶ Setup
sphinx_toolbox.more_autodoc.autonamedtuple
.New in version 0.8.0.
- Parameters
app (
Sphinx
) – The Sphinx application.- Return type