diff options
Diffstat (limited to 'doc/usage/extensions')
| -rw-r--r-- | doc/usage/extensions/autodoc.rst | 81 | ||||
| -rw-r--r-- | doc/usage/extensions/autosectionlabel.rst | 4 | ||||
| -rw-r--r-- | doc/usage/extensions/autosummary.rst | 2 | ||||
| -rw-r--r-- | doc/usage/extensions/coverage.rst | 61 | ||||
| -rw-r--r-- | doc/usage/extensions/doctest.rst | 18 | ||||
| -rw-r--r-- | doc/usage/extensions/graphviz.rst | 4 | ||||
| -rw-r--r-- | doc/usage/extensions/ifconfig.rst | 2 | ||||
| -rw-r--r-- | doc/usage/extensions/inheritance.rst | 2 | ||||
| -rw-r--r-- | doc/usage/extensions/intersphinx.rst | 4 | ||||
| -rw-r--r-- | doc/usage/extensions/math.rst | 2 |
10 files changed, 144 insertions, 36 deletions
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index c920de8..a2a093f 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -1,4 +1,6 @@ -.. highlight:: rest +.. highlight:: rst + +.. _ext-autodoc: :mod:`sphinx.ext.autodoc` -- Include documentation from docstrings ================================================================== @@ -12,13 +14,6 @@ This extension can import the modules you are documenting, and pull in documentation from docstrings in a semi-automatic way. -.. note:: - - For Sphinx (actually, the Python interpreter that executes Sphinx) to find - your module, it must be importable. That means that the module or the - package must be in one of the directories on :data:`sys.path` -- adapt your - :data:`sys.path` in the configuration file accordingly. - .. warning:: :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any @@ -43,6 +38,68 @@ 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 +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. + +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. + + - 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:: + + sys.path.insert(0, os.path.abspath('../src')) + + to your :file:`conf.py`. + + - 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 ---------- @@ -271,7 +328,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, 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 reST formatted. + module whose docstrings are not reStructuredText formatted. .. versionadded:: 0.3 @@ -688,7 +745,7 @@ There are also config values that you can set: * ``'fully-qualified'`` -- Show the module name and its name of typehints * ``'short'`` -- Suppress the leading module names of the typehints - (ex. ``io.StringIO`` -> ``StringIO``) (default) + (e.g. ``io.StringIO`` -> ``StringIO``) (default) .. versionadded:: 4.4 @@ -816,8 +873,8 @@ needed docstring processing in event :event:`autodoc-process-docstring`: .. versionadded:: 4.1 .. versionchanged:: 4.3 - ``bases`` can contain a string as a base class name. It will be processed - as reST mark-up'ed text. + ``bases`` can contain a string as a base class name. + It will be processed as reStructuredText. Skipping members diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst index b5b9b51..29b1c2a 100644 --- a/doc/usage/extensions/autosectionlabel.rst +++ b/doc/usage/extensions/autosectionlabel.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title ============================================================================== @@ -51,6 +51,6 @@ Debugging --------- The ``WARNING: undefined label`` indicates that your reference in -:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vv`` +:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vvv`` (see :option:`-v`) will print all section names and the labels that have been generated for them. This output can help finding the right reference label. diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index a18460b..0a25d8d 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.autosummary` -- Generate autodoc summaries =========================================================== diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst index b9c493b..75ffc0f 100644 --- a/doc/usage/extensions/coverage.rst +++ b/doc/usage/extensions/coverage.rst @@ -6,15 +6,64 @@ This extension features one additional builder, the :class:`CoverageBuilder`. -.. class:: CoverageBuilder +.. todo:: Write this section. - To use this builder, activate the coverage extension in your configuration - file and give ``-M coverage`` on the command line. +.. note:: -.. todo:: Write this section. + The :doc:`sphinx-apidoc </man/sphinx-apidoc>` command can be used to + automatically generate API documentation for all code in a project, + avoiding the need to manually author these documents and keep them up-to-date. + +.. warning:: + + :mod:`~sphinx.ext.coverage` **imports** the modules to be documented. + If any modules have side effects on import, + these will be executed by the coverage builder 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. + +.. note:: + + For Sphinx (actually, the Python interpreter that executes Sphinx) + to find your module, it must be importable. + That means that the module or the package must be in + one of the directories on :data:`sys.path` -- adapt your :data:`sys.path` + in the configuration file accordingly. + +To use this builder, activate the coverage extension in your configuration file +and run ``sphinx-build -M coverage`` on the command line. + + +Builder +------- + +.. py:class:: CoverageBuilder + + +Configuration +------------- + +Several configuration values can be used to specify +what the builder should check: + +.. confval:: coverage_modules + :type: ``list[str]`` + :default: ``[]`` + + List of Python packages or modules to test coverage for. + When this is provided, Sphinx will introspect each package + or module provided in this list as well + as all sub-packages and sub-modules found in each. + When this is not provided, Sphinx will only provide coverage + for Python packages and modules that it is aware of: + that is, any modules documented using the :rst:dir:`py:module` directive + provided in the :doc:`Python domain </usage/domains/python>` + or the :rst:dir:`automodule` directive provided by the + :mod:`~sphinx.ext.autodoc` extension. -Several configuration values can be used to specify what the builder -should check: + .. versionadded:: 7.4 .. confval:: coverage_ignore_modules diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst index 1848e1f..a5fc2c7 100644 --- a/doc/usage/extensions/doctest.rst +++ b/doc/usage/extensions/doctest.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.doctest` -- Test snippets in the documentation =============================================================== @@ -344,12 +344,12 @@ The doctest extension uses the following configuration values: .. confval:: doctest_test_doctest_blocks - If this is a nonempty string (the default is ``'default'``), standard reST - doctest blocks will be tested too. They will be assigned to the group name - given. + If this is a nonempty string (the default is ``'default'``), + standard reStructuredText doctest blocks will be tested too. + They will be assigned to the group name given. - reST doctest blocks are simply doctests put into a paragraph of their own, - like so:: + reStructuredText doctest blocks are simply doctests + put into a paragraph of their own, like so:: Some documentation text. @@ -378,8 +378,8 @@ The doctest extension uses the following configuration values: with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a special directive. - Note though that you can't have blank lines in reST doctest blocks. They - will be interpreted as one block ending and another one starting. Also, - removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in + Note though that you can't have blank lines in reStructuredText doctest blocks. + They will be interpreted as one block ending and another one starting. + Also, removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to achieve that in all code blocks with Python console content. diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst index 231bd36..0cd7cac 100644 --- a/doc/usage/extensions/graphviz.rst +++ b/doc/usage/extensions/graphviz.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.graphviz` -- Add Graphviz graphs ================================================= @@ -66,7 +66,7 @@ It adds these directives: .. rst:directive:option:: layout: layout type of the graph :type: text - The layout of the graph (ex. ``dot``, ``neato`` and so on). A path to the + The layout of the graph (e.g. ``dot``, ``neato`` and so on). A path to the graphviz commands are also allowed. By default, :confval:`graphviz_dot` is used. diff --git a/doc/usage/extensions/ifconfig.rst b/doc/usage/extensions/ifconfig.rst index 837c0b3..17cdbc0 100644 --- a/doc/usage/extensions/ifconfig.rst +++ b/doc/usage/extensions/ifconfig.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.ifconfig` -- Include content based on configuration ==================================================================== diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst index 33284b5..90bbcc3 100644 --- a/doc/usage/extensions/inheritance.rst +++ b/doc/usage/extensions/inheritance.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams ===================================================================== diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst index e81719f..f64b596 100644 --- a/doc/usage/extensions/intersphinx.rst +++ b/doc/usage/extensions/intersphinx.rst @@ -1,3 +1,5 @@ +.. _ext-intersphinx: + :mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation ====================================================================== @@ -143,7 +145,7 @@ linking: Example: - .. code:: python + .. code-block:: python intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 251d721..7d48d3a 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst .. _math-support: |