From 702ba34afff8e2b2d140fd748dcefe7d04dac7cc Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:15:24 +0100 Subject: [PATCH] Restructure ``autodoc`` documentation (#12932) --- doc/usage/extensions/autodoc.rst | 1097 +++++++++++++++++++++--------- 1 file changed, 765 insertions(+), 332 deletions(-) diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 289218f80..c93a5e6d4 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -1,212 +1,713 @@ -.. highlight:: rst - .. _ext-autodoc: :mod:`sphinx.ext.autodoc` -- Include documentation from docstrings ================================================================== -.. module:: sphinx.ext.autodoc +.. py:module:: sphinx.ext.autodoc :synopsis: Include documentation from docstrings. .. index:: pair: automatic; documentation single: docstring -This extension can import the modules you are documenting, and pull in -documentation from docstrings in a semi-automatic way. +This extension can import the modules you are documenting, +and pull in documentation from docstrings in a semi-automatic way. .. warning:: - :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any - modules have side effects on import, these will be executed by ``autodoc`` - when ``sphinx-build`` is run. + :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. + If any modules have side effects on import, + these will be executed by ``autodoc`` when :program:`sphinx-build` is run. - If you document scripts (as opposed to library modules), make sure their main - routine is protected by a ``if __name__ == '__main__'`` condition. + If you document scripts (as opposed to library modules), + make sure that the main routine is protected by + an ``if __name__ == '__main__'`` condition. For this to work, the docstrings must of course be written in correct -reStructuredText. You can then use all of the usual Sphinx markup in the -docstrings, and it will end up correctly in the documentation. Together with -hand-written documentation, this technique eases the pain of having to maintain -two locations for documentation, while at the same time avoiding -auto-generated-looking pure API documentation. +reStructuredText. +You can then use all of the usual Sphinx markup in the docstrings, +and it will end up correctly in the documentation. +Together with hand-written documentation, this technique eases +the pain of having to maintain two locations for documentation, +while at the same time avoiding auto-generated-looking pure API documentation. If you prefer `NumPy`_ or `Google`_ style docstrings over reStructuredText, you can also enable the :mod:`napoleon ` extension. -:mod:`napoleon ` is a preprocessor that converts your -docstrings to correct reStructuredText before :mod:`autodoc` processes them. +:mod:`!napoleon` is a preprocessor that converts docstrings +to correct reStructuredText before ``autodoc`` processes them. .. _Google: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings .. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + Getting started --------------- + Setup -..... -Activate the plugin by adding ``'sphinx.ext.autodoc'`` to the :confval:`extensions` -in your :file:`conf.py`:: +^^^^^ + +Activate the plugin by adding ``'sphinx.ext.autodoc'`` to +the :confval:`extensions` list in :file:`conf.py`: + +.. code-block:: python extensions = [ ... 'sphinx.ext.autodoc', ] -Ensuring the code can be imported -................................. -:mod:`~sphinx.ext.autodoc` analyses the code and docstrings by introspection after -importing the modules. For importing to work, you have to make sure that your -modules can be found by Sphinx and that dependencies can be resolved (if your -module does ``import foo``, but ``foo`` is not available in the python environment -that Sphinx runs in, your module import will fail). +Ensuring the code can be imported +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:mod:`~sphinx.ext.autodoc` analyses the code and docstrings +by introspection after **importing the modules**. +For importing to work, you have to make sure that your modules can be found +by Sphinx and that dependencies can be resolved +(if your module does ``import foo``, but ``foo`` is not available +in the python environment that Sphinx runs in, your module import will fail). There are two ways to ensure this: -1. Use an environment that contains your package and Sphinx. This can e.g. be your - local dev environment (with an editable install), or an environment in CI in - which you install Sphinx and your package. The regular installation process - ensures that your package can be found by Sphinx and that all dependencies are - available. +1. Use an environment that contains your package and Sphinx. + This can e.g. be your local development environment (with an editable install), + or an environment in CI in which you install Sphinx and your package. + The regular installation process ensures that your package can be found + by Sphinx and that all dependencies are available. 2. It is alternatively possible to patch the Sphinx run so that it can operate - directly on the sources; e.g. if you want to be able to do a Sphinx build from a - source checkout. + directly on the sources; + e.g. if you want to be able to do a Sphinx build from a source checkout. - - Patch :data:`sys.path` in your Sphinx :file:`conf.py` to include the folder of - your sources. E.g. if you have a repository structure with :file:`doc/conf.py` - and your package is at :file:`src/mypackage`, then you should add:: + * Patch :data:`sys.path` in :file:`conf.py` to include your source path. + For example if you have a repository structure with :file:`doc/conf.py` + and your package is at :file:`src/my_package`, + then you should add the following to your :file:`conf.py`. - sys.path.insert(0, os.path.abspath('../src')) + .. code-block:: python - to your :file:`conf.py`. + import sys + from pathlib import Path + + sys.path.insert(0, str(Path('..', 'src').resolve())) + + * To cope with missing dependencies, specify the missing modules in + the :confval:`autodoc_mock_imports` setting. - - To cope with missing dependencies, specify the missing modules in - :confval:`autodoc_mock_imports`. Usage -..... +^^^^^ -You can now use the :ref:`autodoc-directives` to add formatted documentation for -Python code elements like functions, classes, modules, etc. For example, to document -the function ``io.open()``, reading its signature and docstring from the source file, -you'd write :: +You can now use the :ref:`autodoc-directives` to add formatted documentation +for Python code elements like functions, classes, modules, etc. +For example, to document the function ``io.open()``, +reading its signature and docstring from the source file, you'd write: + +.. code-block:: rst .. autofunction:: io.open -You can also document whole classes or even modules automatically, using member -options for the auto directives, like :: +You can also document whole classes or even modules automatically, +using member options for the auto directives, like: + +.. code-block:: rst .. automodule:: io :members: +.. tip:: + As a hint to autodoc extension, you can put a ``::`` separator + between the module name and the object name + to let autodoc know the correct module, if it is ambiguous: + + .. code-block:: rst + + .. autoclass:: module.name::Noodle + + +Marking objects as public or private +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* autodoc considers a member private if its docstring contains + ``:meta private:`` in its :ref:`info-field-lists`. + For example: + + .. code-block:: python + + def my_function(my_arg, my_other_arg): + """blah blah blah + + :meta private: + """ + + .. versionadded:: 3.0 + +* autodoc considers a member public if its docstring contains + ``:meta public:`` in its :ref:`info-field-lists`, even if it starts with + an underscore. + For example: + + .. code-block:: python + + def _my_function(my_arg, my_other_arg): + """blah blah blah + + :meta public: + """ + + .. versionadded:: 3.1 + +* autodoc considers a variable member does not have any default value if its + docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`. + Example: + + .. code-block:: python + + var1 = None #: :meta hide-value: + + .. versionadded:: 3.5 + + +.. _doc-comment: + +Doc comments and docstrings +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Python has no built-in support for docstrings for +module data members or class attributes. +To allow documenting these, ``autodoc`` recognises a special format of +:ref:`comment ` called a 'doc comment' or 'documentation comment'. + +These comments start with a colon and an optional space character, +``'#:'`` or ``'#: '``. +To be recognised, the comments must appear either on the same line +as the variable or on one or more lines before the variable. +Multi-line doc-comments must always appear on the lines before the +variable's definition. + +For example, all three of the following variables have valid doc-comments: + +.. code-block:: python + + egg_and_spam = 1.50 #: A simple meal + + #: Spam! Lovely spam! Lovely spam! + egg_bacon_sausage_and_spam = 2.49 + + #: Truly gourmet cuisine for madam; Lobster Thermidor + #: aux Crevettes with a mornay sauce garnished with + #: truffle pate, brandy and a fried egg on top and spam. + lobster_thermidor = 35.00 + +Alternatively, ``autodoc`` can recognise a docstring +on the line immediately following the definition. + +In the the following class definition, +all attributes have documentation recognised by ``autodoc``: + +.. code-block:: python + + class Foo: + """Docstring for class Foo.""" + + #: Doc comment for class attribute Foo.bar. + #: It can have multiple lines. + bar = 1 + + flox = 1.5 #: Doc comment for Foo.flox. One line only. + + baz = 2 + """Docstring for class attribute Foo.baz.""" + + def __init__(self): + #: Doc comment for instance attribute qux. + self.qux = 3 + + self.spam = 4 + """Docstring for instance attribute spam.""" + + .. _autodoc-directives: Directives ---------- -:mod:`autodoc` provides several directives that are versions of the usual -:rst:dir:`py:module`, :rst:dir:`py:class` and so forth. On parsing time, they -import the corresponding module and extract the docstring of the given objects, -inserting them into the page source under a suitable :rst:dir:`py:module`, -:rst:dir:`py:class` etc. directive. +:mod:`autodoc` provides several directives that are versions of +the usual :rst:dir:`py:module`, :rst:dir:`py:class` and so forth. +On parsing time, they import the corresponding module +and extract the docstring of the given objects, +inserting them into the page source under a suitable +:rst:dir:`py:module`, :rst:dir:`py:class` etc. directive. .. note:: - Just as :rst:dir:`py:class` respects the current :rst:dir:`py:module`, - :rst:dir:`autoclass` will also do so. Likewise, :rst:dir:`automethod` will - respect the current :rst:dir:`py:class`. + Just as :rst:dir:`py:class` respects the current + :rst:dir:`py:module`, :rst:dir:`autoclass` will also do so. + Likewise, :rst:dir:`automethod` will respect the current :rst:dir:`py:class`. +Default directive options +^^^^^^^^^^^^^^^^^^^^^^^^^ + +To make any of the options described below the default, +use the :confval:`autodoc_default_options` dictionary in :file:`conf.py`. + +If using defaults for the ``:members:``, ``:exclude-members:``, +``:private-members:``, or ``:special-members:`` options, +setting the option on a directive will override the default. +Instead, to extend the default list with the per-directive option, +the list may be prepended with a plus sign (``+``), +as follows: + +.. code-block:: rst + + .. autoclass:: Noodle + :members: eat + :private-members: +_spicy, _garlickly + +.. tip:: + If using :confval:`autodoc_default_options`, + the defaults can be disabled per-directive with the negated form, + :samp:`:no-{option}:` as an option of the directive + For example: + + .. code-block:: rst + + .. automodule:: foo + :no-undoc-members: + + +Automatically document modules +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. rst:directive:: automodule - autoclass - autoexception - Document a module, class or exception. All three directives will by default - only insert the docstring of the object itself:: + Document a module. + By default, the directive only inserts the docstring of the module itself: - .. autoclass:: Noodle + .. code-block:: rst - will produce source like this:: + .. automodule:: noodles - .. class:: Noodle + will produce source like this: - Noodle's docstring. + .. code-block:: rst - The "auto" directives can also contain content of their own, it will be - inserted into the resulting non-auto directive source after the docstring - (but before any automatic member documentation). + .. py:module:: noodles + + The noodles module. + + The directive can also contain content of its own, + which will be inserted into the resulting non-auto directive source + after the docstring (but before any automatic member documentation). Therefore, you can also mix automatic and non-automatic member documentation, - like so:: + as follows: - .. autoclass:: Noodle - :members: eat, slurp + .. code-block:: rst - .. method:: boil(time=10) + .. automodule:: noodles + :members: Noodle - Boil the noodle *time* minutes. + .. py:function:: boiled_noodle(time=10) + + Create a noodle that has been boiled for *time* minutes. .. rubric:: Options + .. rst:directive:option:: no-index + :type: + + Do not generate an index entry for the documented module + or any auto-documented members. + + .. versionadded:: 0.4 + + .. rst:directive:option:: platform: platforms + :type: comma separated list + + Indicate platforms on which the module is available. + This is identical to :rst:dir:`py:module`'s ``:platform:`` option. + + .. rst:directive:option:: synopsis: purpose + :type: text + + A sentence describing the module's purpose. + This is identical to :rst:dir:`py:module`'s ``:synopsis:`` option. + + .. versionadded:: 0.5 + + .. rst:directive:option:: deprecated + :type: + + Mark a module as deprecated. + This is identical to :rst:dir:`py:module`'s ``:deprecated:`` option. + + .. versionadded:: 0.5 + + .. rst:directive:option:: ignore-module-all + :type: no value + + Do not use ``__all__`` when analysing the module to document. + + .. versionadded:: 1.7 + + .. rubric:: Options for selecting members to document + .. rst:directive:option:: members :type: no value or comma separated list - If set, autodoc will generate document for the members of the target - module, class or exception. + Generate automatic documentation for all members of the target module: - For example:: + .. code-block:: rst - .. automodule:: noodle - :members: + .. automodule:: noodles + :members: - will document all module members (recursively), and :: + 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. - .. autoclass:: Noodle - :members: + To only document certain members, an explicit comma-separated list + may be used as the argument to ``:members:``: - will document all class member methods and properties. + .. code-block:: rst - By default, autodoc will not generate document for the members that are - private, not having docstrings, inherited from super class, or special - members. + .. automodule:: noodles + :members: Noodle - For modules, ``__all__`` will be respected when looking for members unless - you give the ``ignore-module-all`` flag option. Without - ``ignore-module-all``, the order of the members will also be the order in - ``__all__``. + .. rst:directive:option:: exclude-members + :type: comma separated list - You can also give an explicit list of members; only these will then be - documented:: + Exclude the given names from the members to document. + For example: - .. autoclass:: Noodle - :members: eat, slurp + .. code-block:: rst - .. rst:directive:option:: undoc-members + .. automodule:: noodles + :members: + :exclude-members: NoodleBase + + .. versionadded:: 0.6 + + .. rst:directive:option:: imported-members :type: no value - If set, autodoc will also generate document for the members not having - docstrings:: + To prevent documentation of imported classes or functions, + in an :rst:dir:`!automodule` directive with the ``members`` option set, + only module members where the ``__module__`` attribute is equal + to the module name given to ``automodule`` will be documented. - .. automodule:: noodle - :members: - :undoc-members: + Set the ``imported-members`` option if you want to prevent this behavior + and document all available members. + + Note that attributes from imported modules will not be documented, + because attribute documentation is discovered by + parsing the source file of the current module. + + .. versionadded:: 1.2 + + .. rst:directive:option:: undoc-members + :type: + + Generate automatic documentation for members of the target module + that don't have a docstring or doc-comment. + For example: + + .. code-block:: rst + + .. automodule:: noodles + :members: + :undoc-members: .. rst:directive:option:: private-members :type: no value or comma separated list - If set, autodoc will also generate document for the private members - (that is, those named like ``_private`` or ``__private``):: + Generate automatic documentation for private members of the target module. + This includes names with a leading underscore (e.g. ``_private``) + and those members explicitly marked as private with ``:meta private:``. - .. automodule:: noodle - :members: - :private-members: + .. code-block:: rst - It can also take an explicit list of member names to be documented as - arguments:: + .. automodule:: noodles + :members: + :private-members: - .. automodule:: noodle - :members: - :private-members: _spicy, _garlickly + To only document certain private members, an explicit comma-separated list + may be used as the argument to ``:private-members:``: + + .. code-block:: rst + + .. automodule:: noodles + :members: + :private-members: _spicy, _garlickly + + .. versionadded:: 1.1 + .. versionchanged:: 3.2 + The option can now take a comma-separated list of arguments. + + .. rst:directive:option:: special-members + :type: no value or comma separated list + + Generate automatic documentation for special members of the target module, + also known as :ref:`"dunder" names `. + This includes all names enclosed with a double-underscore, + e.g. ``__special__``: + + .. code-block:: rst + + .. automodule:: my.Class + :members: + :special-members: + + To only document certain special members, an explicit comma-separated list + may be used as the argument to ``:special-members:``: + + .. code-block:: rst + + .. automodule:: noodles + :members: + :special-members: __version__ + + .. versionadded:: 1.1 + + .. versionchanged:: 1.2 + The option can now take a comma-separated list of arguments. + + .. rubric:: Options for documented members + + .. rst:directive:option:: member-order + :type: alphabetical, bysource, or groupwise + + Choose the ordering of automatically documented members + (default: ``alphabetical``). + This overrides the :confval:`autodoc_member_order` setting. + + * ``alphabetical``: + Use simple alphabetical order. + * ``groupwise``: + Group by object type (class, function, etc), + use alphabetical order within groups. + * ``bysource``: + Use the order of objects in the module's source. + The ``__all__`` variable can be used to override this order. + + Note that for source order, the module must be a Python module with the + source code available. + + .. versionadded:: 0.6 + .. versionchanged:: 1.0 + Support the ``'bysource'`` option. + + .. rst:directive:option:: show-inheritance + :type: no value + + Enable the ``:show-inheritance:`` option for all members of the module, + if ``:members:`` is enabled. + + .. versionadded:: 0.4 + + +Automatically document classes or exceptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. rst:directive:: autoclass + autoexception + + Document a class. + For exception classes, prefer ``autoexception``. + By default, the directive only inserts the docstring of the class itself: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + + will produce source like this: + + .. code-block:: rst + + .. py:class:: Noodle + + The Noodle class's docstring. + + The directive can also contain content of its own, + which will be inserted into the resulting non-auto directive source + after the docstring (but before any automatic member documentation). + + Therefore, you can also mix automatic and non-automatic member documentation, + as follows: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + :members: eat, slurp + + .. py:method:: boil(time=10) + + Boil the noodle for *time* minutes. + + .. rubric:: Advanced usage + + * It is possible to override the signature for explicitly documented + callable objects (functions, methods, classes) with the regular syntax + that will override the signature gained from introspection: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle(type) + + .. automethod:: eat(persona) + + This is useful if the signature from the method is hidden by a decorator. + + .. versionadded:: 0.4 + + .. rubric:: Options + + .. rst:directive:option:: no-index + :type: + + Do not generate an index entry for the documented class + or any auto-documented members. + + .. versionadded:: 0.4 + + .. rst:directive:option:: class-doc-from + :type: class, init, or both + + Select which docstring will be used for the main body of the directive. + This overrides the global value of :confval:`autoclass_content`. + The possible values are: + + * ``class``: + Only use the class's docstring. + The :meth:`!__init__` method can be separately documented + using the ``:members:`` option or :rst:dir:`automethod`. + * ``init``: + Only use the docstring of the :meth:`!__init__` method. + * ``both`` + Use both, appending the docstring of the :meth:`!__init__` method + to the class's docstring. + + If the :meth:`!__init__` method doesn't exist or has a blank docstring, + ``autodoc`` will attempt to use the :meth:`!__new__` method's docstring, + if it exists and is not blank. + + .. versionadded:: 4.1 + + .. rubric:: Options for selecting members to document + + .. rst:directive:option:: members + :type: no value or comma separated list + + Generate automatic documentation for all members of the target class: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + :members: + + By default, ``autodoc`` only includes public members + with a docstring or :ref:`doc-comment ` (``#:``) + that are attributes of the target class (i.e. not inherited). + + To only document certain members, an explicit comma-separated list + may be used as the argument to ``:members:``: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + :members: eat, slurp + + .. rst:directive:option:: exclude-members + :type: comma separated list + + Exclude the given names from the members to document. + For example: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + :members: + :exclude-members: prepare + + .. versionadded:: 0.6 + + .. rst:directive:option:: inherited-members + :type: comma separated list + + To generate automatic documentation for members inherited + from base classes, use the ``:inherited-members:`` option: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + :members: + :inherited-members: + + This can be combined with the ``:undoc-members:`` option to generate + automatic documentation for *all* available members of the class. + + The members of classes listed in the argument to ``:inherited-members:`` + are excluded from the automatic documentation. + This defaults to :py:class:`python:object` if no argument is provided, + meaning that members of the ``object`` class are not documented. + To include these, use ``None`` as the argument. + + For example; If your class ``MyList`` is derived from ``list`` class and + you don't want to document ``list.__len__()``, you should specify a + option ``:inherited-members: list`` to avoid special members of list + class. + + .. note:: + Should any of the inherited members use a format other than + reStructuredText for their docstrings, + there may be markup warnings or errors. + + .. versionadded:: 0.3 + + .. versionchanged:: 3.0 + ``:inherited-members:`` now takes the name of a base class + to exclude as an argument. + + .. versionchanged:: 5.0 + A comma separated list of base class names can be used. + + .. rst:directive:option:: undoc-members + :type: no value + + Generate automatic documentation for members of the target class + that don't have a docstring or doc-comment. + For example: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + :members: + :undoc-members: + + .. rst:directive:option:: private-members + :type: no value or comma separated list + + Generate automatic documentation for private members of the target class. + This includes names with a leading underscore (e.g. ``_private``) + and those members explicitly marked as private with ``:meta private:``. + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + :members: + :private-members: + + To only document certain private members, an explicit comma-separated list + may be used as the argument to ``:private-members:``: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + :members: + :private-members: _spicy, _garlickly .. versionadded:: 1.1 .. versionchanged:: 3.2 @@ -215,134 +716,121 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, .. rst:directive:option:: special-members :type: no value or comma separated list - If set, autodoc will also generate document for the special members - (that is, those named like ``__special__``):: + Generate automatic documentation for special members of the target class, + also known as :ref:`"dunder" names `. + This includes all names enclosed with a double-underscore, + e.g. ``__special__``: - .. autoclass:: my.Class - :members: - :special-members: + .. code-block:: rst - It can also take an explicit list of member names to be documented as - arguments:: + .. autoclass:: noodles.Noodle + :members: + :special-members: - .. autoclass:: my.Class - :members: - :special-members: __init__, __name__ + To only document certain special members, an explicit comma-separated list + may be used as the argument to ``:special-members:``: + + .. code-block:: rst + + .. autoclass:: noodles.Noodle + :members: + :special-members: __init__, __name__ .. versionadded:: 1.1 .. versionchanged:: 1.2 - The option can now take arguments + The option can now take a comma-separated list of arguments. - **Options and advanced usage** + .. rubric:: Options for documented members - * If you want to make the ``members`` option (or other options described - below) the default, see :confval:`autodoc_default_options`. + .. rst:directive:option:: member-order + :type: alphabetical, bysource, or groupwise - .. tip:: + Choose the ordering of automatically documented members + (default: ``alphabetical``). + This overrides the :confval:`autodoc_member_order` setting. - You can use a negated form, :samp:`'no-{flag}'`, as an option of - autodoc directive, to disable it temporarily. For example:: + * ``'alphabetical'``: + Use simple alphabetical order. + * ``'groupwise'``: + Group by object type (class, function, etc), + use alphabetical order within groups. + * ``'bysource'``: + Use the order of objects in the module's source. + The ``__all__`` variable can be used to override this order. - .. automodule:: foo - :no-undoc-members: + Note that for source order, the module must be a Python module with the + source code available. - .. tip:: + .. versionadded:: 0.6 + .. versionchanged:: 1.0 + Support the ``'bysource'`` option. - You can use autodoc directive options to temporarily override or - extend default options which takes list as an input. For example:: + .. rst:directive:option:: show-inheritance + :type: no value - .. autoclass:: Noodle - :members: eat - :private-members: +_spicy, _garlickly + Insert the class's base classes after the class signature. - .. versionchanged:: 3.5 - The default options can be overridden or extended temporarily. + .. versionadded:: 0.4 - * autodoc considers a member private if its docstring contains - ``:meta private:`` in its :ref:`info-field-lists`. - For example: - .. code-block:: python +Automatically document function-like objects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - def my_function(my_arg, my_other_arg): - """blah blah blah +.. rst:directive:: autofunction + automethod + autoproperty + autodecorator - :meta private: - """ + Document a function, method, property, or decorator. + By default, the directive only inserts the docstring of the function itself: - .. versionadded:: 3.0 + .. code-block:: rst - * autodoc considers a member public if its docstring contains - ``:meta public:`` in its :ref:`info-field-lists`, even if it starts with - an underscore. - For example: + .. autofunction:: noodles.average_noodle - .. code-block:: python + will produce source like this: - def _my_function(my_arg, my_other_arg): - """blah blah blah + .. code-block:: rst - :meta public: - """ + .. py:function:: noodles.average_noodle - .. versionadded:: 3.1 + The average_noodle function's docstring. - * autodoc considers a variable member does not have any default value if its - docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`. - Example: + The directive can also contain content of its own, + which will be inserted into the resulting non-auto directive source + after the docstring. - .. code-block:: python + Therefore, you can also mix automatic and non-automatic documentation, + as follows: - var1 = None #: :meta hide-value: + .. code-block:: rst - .. versionadded:: 3.5 + .. autofunction:: noodles.average_noodle - * For classes and exceptions, members inherited from base classes will be - left out when documenting all members, unless you give the - ``inherited-members`` option, in addition to ``members``:: + .. note:: For more flexibility, use the :py:class:`!Noodle` class. - .. autoclass:: Noodle - :members: - :inherited-members: + .. versionadded:: 2.0 + :rst:dir:`autodecorator`. + .. versionadded:: 2.1 + :rst:dir:`autoproperty`. - This can be combined with ``undoc-members`` to document *all* available - members of the class or module. + .. note:: - It can take an ancestor class not to document inherited members from it. - By default, members of ``object`` class are not documented. To show them - all, give ``None`` to the option. + If you document decorated functions or methods, + keep in mind that ``autodoc`` retrieves its docstrings + by importing the module and inspecting the ``__doc__`` attribute + of the given function or method. + That means that if a decorator replaces the decorated function with another, + it must copy the original ``__doc__`` to the new function. - For example; If your class ``Foo`` is derived from ``list`` class and - you don't want to document ``list.__len__()``, you should specify a - option ``:inherited-members: list`` to avoid special members of list - class. + .. rubric:: Advanced usage - Another example; If your class Foo has ``__str__`` special method and - autodoc directive has both ``inherited-members`` and ``special-members``, - ``__str__`` will be documented as in the past, but other special method - that are not implemented in your class ``Foo``. + * It is possible to override the signature for explicitly documented + callable objects (functions, methods, classes) with the regular syntax + that will override the signature gained from introspection: - Since v5.0, it can take a comma separated list of ancestor classes. It - allows to suppress inherited members of several classes on the module at - once by specifying the option to :rst:dir:`automodule` directive. - - Note: this will lead to markup errors if the inherited members come from a - module whose docstrings are not reStructuredText formatted. - - .. versionadded:: 0.3 - - .. versionchanged:: 3.0 - - It takes an ancestor class name as an argument. - - .. versionchanged:: 5.0 - - It takes a comma separated list of ancestor class names. - - * It's possible to override the signature for explicitly documented callable - objects (functions, methods, classes) with the regular syntax that will - override the signature gained from introspection:: + .. code-block:: rst .. autoclass:: Noodle(type) @@ -352,155 +840,92 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, .. versionadded:: 0.4 - * The :rst:dir:`automodule`, :rst:dir:`autoclass` and - :rst:dir:`autoexception` directives also support a flag option called - ``show-inheritance``. When given, a list of base classes will be inserted - just below the class signature (when used with :rst:dir:`automodule`, this - will be inserted for every class that is documented in the module). + .. rubric:: Options - .. versionadded:: 0.4 + .. rst:directive:option:: no-index + :type: - * All autodoc directives support the ``no-index`` flag option that has the - same effect as for standard :rst:dir:`py:function` etc. directives: no - index entries are generated for the documented object (and all - autodocumented members). + Do not generate an index entry for the documented function. - .. versionadded:: 0.4 + .. versionadded:: 0.4 - * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and - ``deprecated`` options that the standard :rst:dir:`py:module` directive - supports. - .. versionadded:: 0.5 +Automatically document attributes or data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` - option that can be used to override the global value of - :confval:`autodoc_member_order` for one directive. - - .. versionadded:: 0.6 - - * The directives supporting member documentation also have a - ``exclude-members`` option that can be used to exclude single member names - from documentation, if all members are to be documented. - - .. versionadded:: 0.6 - - * In an :rst:dir:`automodule` directive with the ``members`` option set, only - module members whose ``__module__`` attribute is equal to the module name - as given to ``automodule`` will be documented. This is to prevent - documentation of imported classes or functions. Set the - ``imported-members`` option if you want to prevent this behavior and - document all available members. Note that attributes from imported modules - will not be documented, because attribute documentation is discovered by - parsing the source file of the current module. - - .. versionadded:: 1.2 - - * Add a list of modules in the :confval:`autodoc_mock_imports` to prevent - import errors to halt the building process when some external dependencies - are not importable at build time. - - .. versionadded:: 1.3 - - * As a hint to autodoc extension, you can put a ``::`` separator in between - module name and object name to let autodoc know the correct module name if - it is ambiguous. :: - - .. autoclass:: module.name::Noodle - - * :rst:dir:`autoclass` also recognizes the ``class-doc-from`` option that - can be used to override the global value of :confval:`autoclass_content`. - - .. versionadded:: 4.1 - -.. rst:directive:: autofunction - autodecorator - autodata - automethod +.. rst:directive:: autodata autoattribute - autoproperty - These work exactly like :rst:dir:`autoclass` etc., - but do not offer the options used for automatic member documentation. + Document a module level variable or constant ('data') or class attribute. + By default, the directive only inserts the docstring of the variable itself: - :rst:dir:`autodata` and :rst:dir:`autoattribute` support the ``annotation`` - option. The option controls how the value of variable is shown. If specified - without arguments, only the name of the variable will be printed, and its value - is not shown:: + .. code-block:: rst - .. autodata:: CD_DRIVE - :annotation: + .. autodata:: noodles.FLOUR_TYPE - If the option specified with arguments, it is printed after the name as a value - of the variable:: + will produce source like this: - .. autodata:: CD_DRIVE - :annotation: = your CD device name + .. code-block:: rst - By default, without ``annotation`` option, Sphinx tries to obtain the value of - the variable and print it after the name. + .. py:data:: noodles.FLOUR_TYPE - The ``no-value`` option can be used instead of a blank ``annotation`` to show the - type hint but not the value:: + The FLOUR_TYPE constant's docstring. - .. autodata:: CD_DRIVE - :no-value: + The directive can also contain content of its own, + which will be inserted into the resulting non-auto directive source + after the docstring. - If both the ``annotation`` and ``no-value`` options are used, ``no-value`` has no - effect. + Therefore, you can also mix automatic and non-automatic member documentation, + as follows: - For module data members and class attributes, documentation can either be put - into a comment with special formatting (using a ``#:`` to start the comment - instead of just ``#``), or in a docstring *after* the definition. Comments - need to be either on a line of their own *before* the definition, or - immediately after the assignment *on the same line*. The latter form is - restricted to one line only. + .. code-block:: rst - This means that in the following class definition, all attributes can be - autodocumented:: + .. autodata:: noodles.FLOUR_TYPE - class Foo: - """Docstring for class Foo.""" - - #: Doc comment for class attribute Foo.bar. - #: It can have multiple lines. - bar = 1 - - flox = 1.5 #: Doc comment for Foo.flox. One line only. - - baz = 2 - """Docstring for class attribute Foo.baz.""" - - def __init__(self): - #: Doc comment for instance attribute qux. - self.qux = 3 - - self.spam = 4 - """Docstring for instance attribute spam.""" + .. hint:: Cooking time can vary by which flour type is used. .. versionchanged:: 0.6 - :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract - docstrings. + :rst:dir:`autodata` and :rst:dir:`autoattribute` + can now extract docstrings. .. versionchanged:: 1.1 - Comment docs are now allowed on the same line after an assignment. - .. versionchanged:: 1.2 - :rst:dir:`autodata` and :rst:dir:`autoattribute` have an ``annotation`` - option. - .. versionchanged:: 2.0 - :rst:dir:`autodecorator` added. - .. versionchanged:: 2.1 - :rst:dir:`autoproperty` added. - .. versionchanged:: 3.4 - :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value`` - option. + Doc-comments are now allowed on the same line of an assignment. - .. note:: + .. rubric:: Options - If you document decorated functions or methods, keep in mind that autodoc - retrieves its docstrings by importing the module and inspecting the - ``__doc__`` attribute of the given function or method. That means that if - a decorator replaces the decorated function with another, it must copy the - original ``__doc__`` to the new function. + .. rst:directive:option:: no-index + :type: + + Do not generate an index entry for the documented class + or any auto-documented members. + + .. versionadded:: 0.4 + + .. rst:directive:option:: annotation: value + :type: string + + .. versionadded:: 1.2 + + By default, ``autodoc`` attempts to obtain the type annotation + and value of the variable by introspection, + displaying it after the variable's name. + To override this, a custom string for the variable's value + may be used as the argument to ``annotation``. + + For example, if the runtime value of ``FILE_MODE`` is ``0o755``, + the displayed value will be ``493`` (as ``oct(493) == '0o755'``). + This can be fixed by setting ``:annotation: = 0o755``. + + If ``annotation`` is used without arguments, + no value or type hint will be shown for the variable. + + .. rst:directive:option:: no-value + + .. 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. Configuration @@ -577,7 +1002,9 @@ There are also config values that you can set: The default options for autodoc directives. They are applied to all autodoc directives automatically. It must be a dictionary which maps option names - to the values. For example:: + to the values. For example: + + .. code-block:: python autodoc_default_options = { 'members': 'var1, var2', @@ -711,7 +1138,9 @@ There are also config values that you can set: Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import annotations``. - For example, there is code using a type alias:: + For example, there is code using a type alias: + + .. code-block:: python from __future__ import annotations @@ -721,19 +1150,23 @@ There are also config values that you can set: ... If ``autodoc_type_aliases`` is not set, autodoc will generate internal mark-up - from this code as following:: + from this code as following: - .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + .. code-block:: rst - ... + .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + + ... If you set ``autodoc_type_aliases`` as ``{'AliasType': 'your.module.AliasType'}``, it generates the following document - internally:: + internally: - .. py:function:: f() -> your.module.AliasType: + .. code-block:: rst - ... + .. py:function:: f() -> your.module.AliasType: + + ... .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases .. versionadded:: 3.3