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

DOC: Move autodoc setup/usage to extension docs (#12435)

Browse Source 
Leaving just the link in the quickstart guide
This commit is contained in:
Tim Hoffmann
2024-06-17 11:58:55 +02:00
committed by GitHub
parent b97d14a8b0
commit 1e77e6bc9a
2 changed files with 30 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

34
doc/usage/quickstart.rst
View File

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