more_autodoc.autotypeddict
¶
A Sphinx directive for documenting TypedDicts
in Python.
Only supports typing_extensions
's TypedDict until python/typing#700 is implemented in CPython.
New in version 0.5.0.
Enable sphinx_toolbox.more_autodoc.autotypeddict
by adding the following
to the extensions
variable in your conf.py
:
extensions = [
...
'sphinx_toolbox.more_autodoc.autotypeddict',
]
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.autotypeddict
.
Usage¶
-
.. autotypeddict::
¶ Directive to automatically document a
typing.TypedDict
.The output is based on the
autoclass
directive, but with a few differences:Private and Special members are always excluded.
Undocumented members are always included.
The default sort order is
bysource
.
The following options are available:
-
:noindex:
(flag)¶ Do not generate index entries for the documented object (and all autodocumented members).
-
:alphabetical:
(flag)¶ Sort the keys alphabetically. By default the keys are listed in the order they were defined.
-
:show-inheritance:
(flag)¶ Inserts a list of base classes just below the TypedDict’s signature.
See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html for further information.
-
:typeddict:
¶ Role which provides a cross-reference to the documentation generated by
autotypeddict
.
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 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 | # Examples from
# https://www.python.org/dev/peps/pep-0589/#totality
# https://github.com/python/typing/pull/700
"""
Demo of ``.. autotypeddict::``
"""
# 3rd party
from typing_extensions import TypedDict
__all__ = ["Movie", "Animal", "OldStyleAnimal", "Cat", "Bird", "AquaticBird"]
class Movie(TypedDict):
"""
Represents a movie.
"""
#: The name of the movie.
name: str
#: The movie's release year.
year: int
based_on: str
class _Animal(TypedDict):
"""
Keys required by all animals.
"""
#: The name of the animal
name: str
class Animal(_Animal, total=False):
"""
Optional keys common to all animals.
"""
#: The animal's voice.
voice: str
#: Old style TypedDict for Python 2 and where keys aren't valid Python identifiers.
OldStyleAnimal = TypedDict(
"OldStyleAnimal", {
"animal-name": str,
"animal-voice": str,
}, total=False
)
class Cat(Animal):
"""
A cat.
"""
#: The colour of the cat's fur.
fur_color: str
class Bird(Animal):
"""
A bird.
"""
#: The size of the bird's egg, in mm.
egg_size: float
class AquaticBird(Bird):
#: The bird's habitat (e.g. lake, sea)
habitat: float
|
.. automodule:: autotypeddict_demo
:no-autosummary:
:exclude-members: Movie,AquaticBird,OldStyleAnimal
.. autotypeddict:: autotypeddict_demo.Movie
This function takes a single argument, the :typeddict:`~.Movie` to watch.
Demo of .. autotypeddict::
This function takes a single argument, the Movie
to watch.
API Reference¶
Classes:
|
Sphinx autodoc |
Functions:
|
-
class
TypedDictDocumenter
(*args)[source]¶ Bases:
ClassDocumenter
Sphinx autodoc
Documenter
for documentingtyping.TypedDict
s.Methods:
add_content
(more_content[, no_docstring])Add the autodocumenter content.
can_document_member
(member, membername, …)Called to see if a member can be documented by this documenter.
document_keys
(keys, types, docstrings)Document keys in a
typing.TypedDict
.document_members
([all_members])Generate reST for member documentation.
filter_members
(members, want_all)Filter the given member list.
format_signature
(**kwargs)Typed Dicts do not have a signature.
sort_members
(documenters, order)Sort the TypedDict’s members.
-
classmethod
can_document_member
(member, membername, isattr, parent)[source]¶ Called to see if a member can be documented by this documenter.
-
document_keys
(keys, types, docstrings)[source]¶ Document keys in a
typing.TypedDict
.
-
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.autotypeddict
.- Parameters
app (
Sphinx
) – The Sphinx application.- Return type