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.
-
: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