diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 4c03a3551a9..b4b698e9beb 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -36,9 +36,21 @@ docstrings to correct reStructuredText before :mod:`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`:: + + 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 @@ -69,6 +81,23 @@ There are two ways to ensure this: - 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 :: + + .. autofunction:: io.open + +You can also document whole classes or even modules automatically, using member +options for the auto directives, like :: + + .. automodule:: io + :members: + +.. _autodoc-directives: Directives ---------- diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index fcbfa80ee53..2f89b65b169 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -259,43 +259,9 @@ source files, in documentation strings. Sphinx supports the inclusion of docstrings from your modules with an :dfn:`extension` (an extension is a Python module that provides additional features for Sphinx projects) called *autodoc*. -In order to use *autodoc*, you need to activate it in :file:`conf.py` by -putting the string ``'sphinx.ext.autodoc'`` into the list assigned to the -:confval:`extensions` config value:: - - extensions = ['sphinx.ext.autodoc'] - -Then, you have a few additional directives at your disposal. For example, to -document the function ``io.open()``, reading its signature and -docstring from the source file, you'd write this:: - - .. autofunction:: io.open - -You can also document whole classes or even modules automatically, using member -options for the auto directives, like :: - - .. automodule:: io - :members: - -*autodoc* needs to import your modules in order to extract the docstrings. -Therefore, you must add the appropriate path to :py:data:`sys.path` in your -:file:`conf.py`. - -.. 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. - - If you document scripts (as opposed to library modules), make sure their - main routine is protected by a ``if __name__ == '__main__'`` condition. - |more| See :mod:`sphinx.ext.autodoc` for the complete description of the features of autodoc. - -.. todo:: Move this doc to another section - Intersphinx -----------