diff --git a/doc/changes/1.8.rst b/doc/changes/1.8.rst index ac9483bc5..a792e94f0 100644 --- a/doc/changes/1.8.rst +++ b/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`) diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 1d2c60dc4..f4d8f6a7f 100644 --- a/doc/extdev/deprecated.rst +++ b/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` diff --git a/doc/usage/domains/restructuredtext.rst b/doc/usage/domains/restructuredtext.rst index 639b6860a..a675ed557 100644 --- a/doc/usage/domains/restructuredtext.rst +++ b/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```. diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index c93a5e6d4..25acdd211 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/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 ` (``#:``). 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: ` + 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 `. + also known as :ref:`'dunder' names `. 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: ` + 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 `. + also known as :ref:`'dunder' names `. 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