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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
.. highlight:: rest
Configuration of the sphinx extension
=====================================
The module provides 3 additional configuration values, one event and new
flags for the autodoc directives :rst:dir:`autoclass` and :rst:dir:`automodule`.
.. _autodoc-flags:
Additional flags for autodoc directives
---------------------------------------
The most important new flag for the :rst:dir:`autoclass` and
:rst:dir:`automodule` directives is the ``autosummary`` flag. If you want to
have an automatically generated summary to your class or module, you have to
add this flag, e.g. via::
.. autodoc:: MyClass
:autosummary:
or in the :confval:`autodoc_default_options` configuration value of sphinx
via
.. code-block:: python
autodoc_default_options = {'autosummary': True}
See also the usage in the :ref:`examples` section.
The other additional flags lets you control what should be in the autosummary
table: these are
- ``autosummary-private-members``
- ``autosummary-undoc-members``
- ``autosummary-inherited-members``
- ``autosummary-special-members``
- ``autosummary-exlude-members``
- ``autosummary-imported-members``
- ``autosummary-ignore-module-all``
- ``autosummary-members``
They are essentially the same as the options for :mod:`~sphinx.ext.autodoc`
(i.e. ``private-members`` or ``members``), but they only affect the
autosummary table (see the example in :ref:`summary-table-example`).
``autosummary-no-nesting``
The new additional flag ``autosummary-no-nesting`` only generates
autosummary tables for a module, but not for members within. See
example about :ref:`no-nesting-example`.
``autosummary-sections``
Select which sections to generate the autosummary for. Usage is like
``:autosummary-sections: Methods ;; Attributes``. When omitted, all sections
are generated. See the example about :ref:`select-sections-example`
``autosummary-no-titles``
Do not add section titles above each autosummary table
``autosummary-force-inline``
Force adding the autosummary, even it is already contained in the class
or module docstring. See the example about :ref:`autosummary-position-example`
``autosummary-nosignatures``
Do not show function signatures in the summary table.
.. _directives:
Directives
----------
.. rst:directive:: autoclasssumm
This class generates the autosummary tables for the given class. You can
use the same options as for the ``autoclass`` directive. You can select a
specific section and omit the title via::
.. autoclasssumm:: MyClass
:autosummary-sections: Methods
:autosummary-no-titles:
By default, this directives also sets the `:members:` option unless you
specify `:no-members`.
.. rst:directive:: autoexceptionsumm
The same as the ``autoclasssumm`` directive, just for an ``Exception``
subclass.
.. rst:directive:: automodulesumm
The same as the ``autoclasssumm`` directive, just for a module.
.. _confvals:
Configuration values and events
-------------------------------
.. event:: autodocsumm-grouper (app, what, name, obj, section, parent)
Emitted when autodocsumm has to determine the section for a member in the
table of contents. If the return value is None, the given `section` will be
used.
:param app: the :class:`~sphinx.application.Sphinx` application object
:param what: the type of the object which the docstring belongs to (one of
``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
``"attribute"``)
:param name: the fully qualified name of the object
:param obj: the member object
:param section: The section title that would be given to the object
automatically (one of ``"Classes"``, ``"Exceptions"``, ``"Functions"``,
``"Methods"``, ``"Attributes"``, ``"Data"``)
:param parent: The parent object holding the member `obj`
.. confval:: autodata_content
As you can include the ``__init__`` method documentation for via the
:confval:`autoclass_content <sphinx:autoclass_content>` configuration value,
this configuration value lets you include the documentation from the
``__call__`` method. Possible values are
class
To only use the class documentation
call
To only use the documentation from the ``__call__`` method
both
To use the documentation from all.
The default is ``'call'``
.. confval:: document_data
To include the string representation of specific data objects. You may
provide a list of fully qualified object names (e.g. in the form of
``'zipfile.ZipFile'``) or ``True`` or ``False``
.. confval:: not_document_data
To exclude the string representation of specific data objects. You may
provide a list of fully qualified object names (e.g. in the form of
``'zipfile.ZipFile'``) or ``True`` or ``False``
.. confval:: autodocsumm_section_sorter
When ``True`` the summarizing sections will be sorted alphanumerically by
their section title. Alternatively a callable can be set that is passed to
:func:`sorted` as key argument to sort the the summary sections by their
name.
The default value is ``None``.
Example usage with a tuple that defines an arbitrary order:
.. code-block:: python
sections_order = ("Public methods", "Attributes", "Private methods")
autodocsumm_section_sorter = lambda title: sections_order.index(title)
An example for cases that only ensures that "Constructors" are always listed
first and "Attributes" while not failing when encountering undefined section
weights:
.. code-block:: python
section_weights = {"Attributes": 100, "Constructors": -100}
autodocsumm_section_sorter = lambda title: sections_weights.get(title, 0)
|
