Improve `autodoc` docs (#12935)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>

doc/changes/1.8.rst

@@ -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`)

doc/extdev/deprecated.rst

@@ -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`

doc/usage/domains/restructuredtext.rst

@@ -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```.

doc/usage/extensions/autodoc.rst

@@ -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.
+      use the ``:no-value:`` option.
-      If both the ``annotation`` and ``no-value`` options are used,
+      If both the ``:annotation:`` and ``:no-value:`` options are used,
-      ``no-value`` has no effect.
+      ``: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"``
+   ``'class'``
-      Only the class' docstring is inserted.  This is the default.  You can
+      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
+   Define the order in which :rst:dir:`automodule` and :rst:dir:`autoclass`
-   alphabetical (value ``'alphabetical'``), by member type (value
+   members are listed. Supported values are:
-   ``'groupwise'``) or by source order (value ``'bysource'``).  The default is
-   alphabetical.
 
-   Note that for source order, the module must be a Python module with the
+   * ``'alphabetical'``:
-   source code available.
+     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'``,
+   The supported options are:
-   ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
+
-   ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``,
+   * ``'members'``: See :rst:dir:`automodule:members`.
-   ``'imported-members'``, ``'exclude-members'``, ``'class-doc-from'`` and
+   * ``'undoc-members'`` See :rst:dir:`automodule:undoc-members`.
-   ``'no-value'``.
+   * ``'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
+   This value controls whether the types of
-   values are documented when ``autodoc_typehints`` is set to ``description``.
+   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
+   * ``'all'``:
-   parameters and return values, whether they are documented or not.
+     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
+   * ``'documented'``:
-   or a return value that is already documented by the docstring.
+     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
+   * ``'documented_params'``:
-   parameter is documented in the docstring. The return type is always
+     Parameter types will only be annotated if the
-   annotated (except if it is ``None``).
+     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
+   :mod:`autodoc` supports suppressing warning messages
-   :confval:`suppress_warnings`.  It allows following warnings types in
+   via :confval:`suppress_warnings`.
-   addition:
+   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"``,
+      ``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'method'``,
-      ``"attribute"``)
+      ``'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"``,
+      ``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'method'``,
-      ``"attribute"``)
+      ``'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"``,
+      ``'module'``, ``'class'``, ``'exception'``, ``'function'``, ``'method'``,
-      ``"attribute"``)
+      ``'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