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# Examples from
2# https://docs.python.org/3/library/typing.html#typing.NamedTuple
3# https://www.python.org/dev/peps/pep-0589/#totality
4# https://github.com/python/typing/pull/700
5
6# stdlib
7import collections
8from typing import NamedTuple
9
10__all__ = ["Animal", "Employee", "Movie"]
11
12
13class Animal(NamedTuple):
14 """
15 An animal.
16
17 :param name: The name of the animal.
18 :param voice: The animal's voice.
19 """
20
21 name: str
22 voice: str
23
24
25class Employee(NamedTuple):
26 """
27 Represents an employee.
28
29 :param id: The employee's ID number
30 """
31
32 #: The employee's name
33 name: str
34
35 id: int = 3
36
37 def __repr__(self) -> str:
38 return f'<Employee {self.name}, id={self.id}>'
39
40 def is_executive(self) -> bool:
41 """
42 Returns whether the employee is an executive.
43
44 Executives have ID numbers < 10.
45 """
46
47
48class Movie(NamedTuple):
49 """
50 Represents a movie.
51 """
52
53 #: The name of the movie.
54 name: str
55
56 #: The movie's release year.
57 year: int
58
59 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