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