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# Examples from
2# https://www.python.org/dev/peps/pep-0589/#totality
3# https://github.com/python/typing/pull/700
4"""
5Demo of ``.. autotypeddict::``
6"""
7
8# 3rd party
9from typing_extensions import TypedDict
10
11__all__ = ["Movie", "Animal", "OldStyleAnimal", "Cat", "Bird", "AquaticBird"]
12
13
14class Movie(TypedDict):
15 """
16 Represents a movie.
17 """
18
19 #: The name of the movie.
20 name: str
21
22 #: The movie's release year.
23 year: int
24
25 based_on: str
26
27
28class _Animal(TypedDict):
29 """
30 Keys required by all animals.
31 """
32
33 #: The name of the animal
34 name: str
35
36
37class Animal(_Animal, total=False):
38 """
39 Optional keys common to all animals.
40 """
41
42 #: The animal's voice.
43 voice: str
44
45
46#: Old style TypedDict for Python 2 and where keys aren't valid Python identifiers.
47OldStyleAnimal = TypedDict(
48 "OldStyleAnimal", {
49 "animal-name": str,
50 "animal-voice": str,
51 }, total=False
52 )
53
54
55class Cat(Animal):
56 """
57 A cat.
58 """
59
60 #: The colour of the cat's fur.
61 fur_color: str
62
63
64class Bird(Animal):
65 """
66 A bird.
67 """
68
69 #: The size of the bird's egg, in mm.
70 egg_size: float
71
72
73class AquaticBird(Bird):
74
75 #: The bird's habitat (e.g. lake, sea)
76 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.
- setup(app)[source]¶
Setup
sphinx_toolbox.more_autodoc.autotypeddict
.- Parameters
app (
Sphinx
) – The Sphinx application.- Return type