IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Improve `autodoc` docs (#12935)

Browse Source 
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
This commit is contained in:
Tim Hoffmann 2024-10-03 01:02:48 +02:00 committed by GitHub
parent 3d211368bd
commit b16e196a60
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 121 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/changes/1.8.rst
View File

@ -147,7 +147,7 @@ Bugs fixed
----------
* #5418: Incorrect default path for sphinx-build -d/doctrees files
* #5421: autodoc emits deprecation warning for :confval:`autodoc_default_flags`
* #5421: autodoc emits deprecation warning for :confval:`!autodoc_default_flags`
* #5422: lambda object causes PicklingError on storing environment
* #5417: Sphinx fails to build with syntax error in Python 2.7.5
* #4911: add latexpdf to make.bat for non make-mode
@ -251,7 +251,7 @@ Deprecated
1.8.0b1
* :confval:`!source_parsers` is deprecated
* :confval:`autodoc_default_flags` is deprecated
* :confval:`!autodoc_default_flags` is deprecated
* quickstart: ``--epub`` option becomes default, so it is deprecated
* Drop function based directive support. For now, Sphinx only supports class
based directives (see :class:`~docutils.parsers.rst.Directive`)

2
doc/extdev/deprecated.rst
View File

@ -1454,7 +1454,7 @@ The following is a list of deprecated interfaces.
- 4.0
- :meth:`~sphinx.application.Sphinx.add_js_file`
* - :confval:`autodoc_default_flags`
* - :confval:`!autodoc_default_flags`
- 1.8
- 4.0
- :confval:`autodoc_default_options`

11
doc/usage/domains/restructuredtext.rst
View File

@ -97,4 +97,13 @@ The reStructuredText domain (name **rst**) provides the following directives:
These roles are provided to refer to the described objects:
.. rst:role:: rst:dir
rst:role
Reference directives and directive options. Examples:
* Use ``:rst:dir:`my-directive``` to reference a directive.
* Use ``:rst:dir:`my-directive:my-option``` to reference a
directive option.
.. rst:role:: rst:role
Reference a role. Example: ``:rst:role:`my-role```.

180
doc/usage/extensions/autodoc.rst
View File

@ -9,6 +9,9 @@
.. index:: pair: automatic; documentation
single: docstring
.. role:: code-py(code)
:language: Python
This extension can import the modules you are documenting,
and pull in documentation from docstrings in a semi-automatic way.
@ -367,7 +370,8 @@ Automatically document modules
By default, ``autodoc`` only includes public members
with a docstring or :ref:`doc-comment <doc-comment>` (``#:``).
If ``__all__`` exists, it will be used to define which members are public,
unless the ``:ignore-module-all:`` option is set.
unless the :rst:dir:`:ignore-module-all: <automodule:ignore-module-all>`
option is set.
To only document certain members, an explicit comma-separated list
may be used as the argument to ``:members:``:
@ -451,7 +455,7 @@ Automatically document modules
:type: no value or comma separated list
Generate automatic documentation for special members of the target module,
also known as :ref:`"dunder" names <python:specialnames>`.
also known as :ref:`'dunder' names <python:specialnames>`.
This includes all names enclosed with a double-underscore,
e.g. ``__special__``:
@ -503,7 +507,8 @@ Automatically document modules
.. rst:directive:option:: show-inheritance
:type: no value
Enable the ``:show-inheritance:`` option for all members of the module,
Enable the :rst:dir:`:show-inheritance: <autoclass:show-inheritance>`
option for all members of the module,
if ``:members:`` is enabled.
.. versionadded:: 0.4
@ -516,7 +521,7 @@ Automatically document classes or exceptions
autoexception
Document a class.
For exception classes, prefer ``autoexception``.
For exception classes, prefer ``.. autoexception::``.
By default, the directive only inserts the docstring of the class itself:
.. code-block:: rst
@ -586,7 +591,7 @@ Automatically document classes or exceptions
using the ``:members:`` option or :rst:dir:`automethod`.
* ``init``:
Only use the docstring of the :meth:`!__init__` method.
* ``both``
* ``both``:
Use both, appending the docstring of the :meth:`!__init__` method
to the class's docstring.
@ -717,7 +722,7 @@ Automatically document classes or exceptions
:type: no value or comma separated list
Generate automatic documentation for special members of the target class,
also known as :ref:`"dunder" names <python:specialnames>`.
also known as :ref:`'dunder' names <python:specialnames>`.
This includes all names enclosed with a double-underscore,
e.g. ``__special__``:
@ -915,7 +920,7 @@ Automatically document attributes or data
the displayed value will be ``493`` (as ``oct(493) == '0o755'``).
This can be fixed by setting ``:annotation: = 0o755``.
If ``annotation`` is used without arguments,
If ``:annotation:`` is used without arguments,
no value or type hint will be shown for the variable.
.. rst:directive:option:: no-value
@ -923,9 +928,9 @@ Automatically document attributes or data
.. versionadded:: 3.4
To display the type hint of the variable without a value,
use the ``no-value`` option.
If both the ``annotation`` and ``no-value`` options are used,
``no-value`` has no effect.
use the ``:no-value:`` option.
If both the ``:annotation:`` and ``:no-value:`` options are used,
``:no-value:`` has no effect.
Configuration
@ -934,18 +939,20 @@ Configuration
There are also config values that you can set:
.. confval:: autoclass_content
:type: :code-py:`str`
:default: :code-py:`'class'`
This value selects what content will be inserted into the main body of an
:rst:dir:`autoclass` directive. The possible values are:
``"class"``
Only the class' docstring is inserted. This is the default. You can
``'class'``
Only the class' docstring is inserted. You can
still document ``__init__`` as a separate method using
:rst:dir:`automethod` or the ``members`` option to :rst:dir:`autoclass`.
``"both"``
``'both'``
Both the class' and the ``__init__`` method's docstring are concatenated
and inserted.
``"init"``
``'init'``
Only the ``__init__`` method's docstring is inserted.
.. versionadded:: 0.3
@ -957,48 +964,47 @@ There are also config values that you can set:
.. versionadded:: 1.4
.. confval:: autodoc_class_signature
:type: :code-py:`str`
:default: :code-py:`'mixed'`
This value selects how the signature will be displayed for the class defined
by :rst:dir:`autoclass` directive. The possible values are:
``"mixed"``
``'mixed'``
Display the signature with the class name.
``"separated"``
``'separated'``
Display the signature as a method.
The default is ``"mixed"``.
.. versionadded:: 4.1
.. confval:: autodoc_member_order
:type: :code-py:`str`
:default: :code-py:`'alphabetical'`
This value selects if automatically documented members are sorted
alphabetical (value ``'alphabetical'``), by member type (value
``'groupwise'``) or by source order (value ``'bysource'``). The default is
alphabetical.
Define the order in which :rst:dir:`automodule` and :rst:dir:`autoclass`
members are listed. Supported values are:
Note that for source order, the module must be a Python module with the
source code available.
* ``'alphabetical'``:
Use alphabetical order.
* ``'groupwise'``: order by member type. The order is:
* for modules, exceptions, classes, functions, data
* for classes: methods, then properties and attributes
Members are ordered alphabetically within groups.
* ``'bysource'``:
Use the order in which the members appear in the source code.
This requires that the module must be a Python module with the
source code available.
.. versionadded:: 0.6
.. versionchanged:: 1.0
Support for ``'bysource'``.
.. confval:: autodoc_default_flags
This value is a list of autodoc directive flags that should be automatically
applied to all autodoc directives. The supported flags are ``'members'``,
``'undoc-members'``, ``'private-members'``, ``'special-members'``,
``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``
and ``'exclude-members'``.
.. versionadded:: 1.0
.. deprecated:: 1.8
Integrated into :confval:`autodoc_default_options`.
.. confval:: autodoc_default_options
:type: :code-py:`dict[str, str | bool]`
:default: :code-py:`{}`
The default options for autodoc directives. They are applied to all autodoc
directives automatically. It must be a dictionary which maps option names
@ -1017,11 +1023,20 @@ There are also config values that you can set:
Setting ``None`` or ``True`` to the value is equivalent to giving only the
option name to the directives.
The supported options are ``'members'``, ``'member-order'``,
``'undoc-members'``, ``'private-members'``, ``'special-members'``,
``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``,
``'imported-members'``, ``'exclude-members'``, ``'class-doc-from'`` and
``'no-value'``.
The supported options are:
* ``'members'``: See :rst:dir:`automodule:members`.
* ``'undoc-members'`` See :rst:dir:`automodule:undoc-members`.
* ``'private-members'``: See :rst:dir:`automodule:private-members`.
* ``'special-members'``: See :rst:dir:`automodule:special-members`.
* ``'inherited-members'``: See :rst:dir:`autoclass:inherited-members`.
* ``'imported-members'``: See :rst:dir:`automodule:imported-members`.
* ``'exclude-members'``: See :rst:dir:`automodule:exclude-members`.
* ``'ignore-module-all'``: See :rst:dir:`automodule:ignore-module-all`.
* ``'member-order'``: See :rst:dir:`automodule:member-order`.
* ``'show-inheritance'``: See :rst:dir:`autoclass:show-inheritance`.
* ``'class-doc-from'``: See :rst:dir:`autoclass:class-doc-from`.
* ``'no-value'``: See :rst:dir:`autodata:no-value`.
.. versionadded:: 1.8
@ -1038,6 +1053,8 @@ There are also config values that you can set:
Added ``'no-value'``.
.. confval:: autodoc_docstring_signature
:type: :code-py:`bool`
:default: :code-py:`True`
Functions imported from C modules cannot be introspected, and therefore the
signature for such functions cannot be automatically determined. However, it
@ -1063,6 +1080,8 @@ There are also config values that you can set:
Overloaded signatures do not need to be separated by a backslash
.. confval:: autodoc_mock_imports
:type: :code-py:`list[str]`
:default: :code-py:`[]`
This value contains a list of modules to be mocked up. This is useful when
some external dependencies are not met at build time and break the building
@ -1071,7 +1090,7 @@ There are also config values that you can set:
.. code-block:: python
autodoc_mock_imports = ["django"]
autodoc_mock_imports = ['django']
Will mock all imports under the ``django`` package.
@ -1082,11 +1101,13 @@ There are also config values that you can set:
should be mocked.
.. confval:: autodoc_typehints
:type: :code-py:`str`
:default: :code-py:`'signature'`
This value controls how to represent typehints. The setting takes the
following values:
* ``'signature'`` -- Show typehints in the signature (default)
* ``'signature'`` -- Show typehints in the signature
* ``'description'`` -- Show typehints as content of the function or method
The typehints of overloaded functions or methods will still be represented
in the signature.
@ -1108,19 +1129,24 @@ There are also config values that you can set:
New option ``'both'`` is added.
.. confval:: autodoc_typehints_description_target
:type: :code-py:`str`
:default: :code-py:`'all'`
This value controls whether the types of undocumented parameters and return
values are documented when ``autodoc_typehints`` is set to ``description``.
This value controls whether the types of
undocumented parameters and return values are documented
when :confval:`autodoc_typehints` is set to ``'description'``.
Supported values:
The default value is ``"all"``, meaning that types are documented for all
parameters and return values, whether they are documented or not.
When set to ``"documented"``, types will only be documented for a parameter
or a return value that is already documented by the docstring.
With ``"documented_params"``, parameter types will only be annotated if the
parameter is documented in the docstring. The return type is always
annotated (except if it is ``None``).
* ``'all'``:
Types are documented for all parameters and return values,
whether they are documented or not.
* ``'documented'``:
Types will only be documented for a parameter
or a return value that is already documented by the docstring.
* ``'documented_params'``:
Parameter types will only be annotated if the
parameter is documented in the docstring. The return type is always
annotated (except if it is ``None``).
.. versionadded:: 4.0
@ -1129,10 +1155,12 @@ There are also config values that you can set:
New option ``'documented_params'`` is added.
.. confval:: autodoc_type_aliases
:type: :code-py:`dict[str, str]`
:default: :code-py:`{}`
A dictionary for users defined `type aliases`__ that maps a type name to the
full-qualified object name. It is used to keep type aliases not evaluated in
the document. Defaults to empty (``{}``).
the document.
The type aliases are only available if your program enables :pep:`Postponed
Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import
@ -1172,13 +1200,15 @@ There are also config values that you can set:
.. versionadded:: 3.3
.. confval:: autodoc_typehints_format
:type: :code-py:`str`
:default: :code-py:`'short'`
This value controls the format of typehints. The setting takes the
following values:
* ``'fully-qualified'`` -- Show the module name and its name of typehints
* ``'short'`` -- Suppress the leading module names of the typehints
(e.g. ``io.StringIO`` -> ``StringIO``) (default)
(e.g. ``io.StringIO`` -> ``StringIO``)
.. versionadded:: 4.4
@ -1187,6 +1217,8 @@ There are also config values that you can set:
The default setting was changed to ``'short'``
.. confval:: autodoc_preserve_defaults
:type: :code-py:`bool`
:default: :code-py:`False`
If True, the default argument values of functions will be not evaluated on
generating document. It preserves them as is in the source code.
@ -1197,32 +1229,36 @@ There are also config values that you can set:
in the future.
.. confval:: autodoc_warningiserror
:type: :code-py:`bool`
:default: :code-py:`True`
This value controls the behavior of :option:`sphinx-build --fail-on-warning`
during importing modules.
If ``False`` is given, autodoc forcedly suppresses the error if the imported
module emits warnings. By default, ``True``.
module emits warnings.
.. versionchanged:: 8.1
This option now has no effect as :option:`!--fail-on-warning`
no longer exits early.
.. confval:: autodoc_inherit_docstrings
:type: :code-py:`bool`
:default: :code-py:`True`
This value controls the docstrings inheritance.
If set to True the docstring for classes or methods, if not explicitly set,
is inherited from parents.
The default is ``True``.
.. versionadded:: 1.7
.. confval:: suppress_warnings
:no-index:
:type: :code-py:`Sequence[str]`
:default: :code-py:`()`
:mod:`autodoc` supports to suppress warning messages via
:confval:`suppress_warnings`. It allows following warnings types in
addition:
:mod:`autodoc` supports suppressing warning messages
via :confval:`suppress_warnings`.
It defines the following additional warnings types:
* autodoc
* autodoc.import_object
@ -1243,8 +1279,8 @@ autodoc provides the following additional events:
:param app: the Sphinx application object
:param what: the type of the object which the docstring belongs to (one of
``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
``"attribute"``)
``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'method'``,
``'attribute'``)
:param name: the fully qualified name of the object
:param obj: the object itself
:param options: the options given to the directive: an object with attributes
@ -1274,8 +1310,8 @@ autodoc provides the following additional events:
:param app: the Sphinx application object
:param what: the type of the object which the docstring belongs to (one of
``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
``"attribute"``)
``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'method'``,
``'attribute'``)
:param name: the fully qualified name of the object
:param obj: the object itself
:param options: the options given to the directive: an object with attributes
@ -1283,10 +1319,10 @@ autodoc provides the following additional events:
``no-index`` that are true if the flag option of same name was given to the
auto directive
:param signature: function signature, as a string of the form
``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't
``'(parameter_1, parameter_2)'``, or ``None`` if introspection didn't
succeed and signature wasn't specified in the directive.
:param return_annotation: function return annotation as a string of the form
``" -> annotation"``, or ``None`` if there is no return annotation
``' -> annotation'``, or ``None`` if there is no return annotation
The :mod:`sphinx.ext.autodoc` module provides factory functions for commonly
needed docstring processing in event :event:`autodoc-process-docstring`:
@ -1335,8 +1371,8 @@ member should be included in the documentation by using the following event:
:param app: the Sphinx application object
:param what: the type of the object which the docstring belongs to (one of
``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
``"attribute"``)
``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'method'``,
``'attribute'``)
:param name: the fully qualified name of the object
:param obj: the object itself
:param skip: a boolean indicating if autodoc will skip this member if the