-
Notifications
You must be signed in to change notification settings - Fork 2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch '4.x' into 9683_add_css_file
- Loading branch information
Showing
27 changed files
with
721 additions
and
143 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
name: Test with the HEAD of docutils | ||
|
||
on: | ||
schedule: | ||
- cron: "0 0 * * SUN" | ||
workflow_dispatch: | ||
|
||
jobs: | ||
test: | ||
runs-on: ubuntu-latest | ||
|
||
steps: | ||
- uses: actions/checkout@v2 | ||
- name: Set up Python | ||
uses: actions/setup-python@v2 | ||
- name: Check Python version | ||
run: python --version | ||
- name: Unpin docutils | ||
run: sed -i -e "s/'docutils>=.*'/'docutils'/" setup.py | ||
- name: Install graphviz | ||
run: sudo apt-get install graphviz | ||
- name: Install dependencies | ||
run: pip install -U tox codecov | ||
- name: Run Tox | ||
run: tox -e du-latest -- -vv |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,166 @@ | ||
Automatic documentation generation from code | ||
============================================ | ||
|
||
In the :ref:`previous section <tutorial-describing-objects>` of the tutorial | ||
you manually documented a Python function in Sphinx. However, the description | ||
was out of sync with the code itself, since the function signature was not | ||
the same. Besides, it would be nice to reuse `Python | ||
docstrings <https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring>`_ | ||
in the documentation, rather than having to write the information in two | ||
places. | ||
|
||
Fortunately, :doc:`the autodoc extension </usage/extensions/autodoc>` provides this | ||
functionality. | ||
|
||
Reusing signatures and docstrings with autodoc | ||
---------------------------------------------- | ||
|
||
To use autodoc, first add it to the list of enabled extensions: | ||
|
||
.. code-block:: python | ||
:caption: docs/source/conf.py | ||
:emphasize-lines: 4 | ||
extensions = [ | ||
'sphinx.ext.duration', | ||
'sphinx.ext.doctest', | ||
'sphinx.ext.autodoc', | ||
] | ||
Next, move the content of the ``.. py:function`` directive to the function | ||
docstring in the original Python file, as follows: | ||
|
||
.. code-block:: python | ||
:caption: lumache.py | ||
:emphasize-lines: 2-11 | ||
def get_random_ingredients(kind=None): | ||
""" | ||
Return a list of random ingredients as strings. | ||
:param kind: Optional "kind" of ingredients. | ||
:type kind: list[str] or None | ||
:raise lumache.InvalidKindError: If the kind is invalid. | ||
:return: The ingredients list. | ||
:rtype: list[str] | ||
""" | ||
return ["shells", "gorgonzola", "parsley"] | ||
Finally, replace the ``.. py:function`` directive from the Sphinx documentation | ||
with :rst:dir:`autofunction`: | ||
|
||
.. code-block:: rst | ||
:caption: docs/source/usage.rst | ||
:emphasize-lines: 3 | ||
you can use the ``lumache.get_random_ingredients()`` function: | ||
.. autofunction:: lumache.get_random_ingredients | ||
If you now build the HTML documentation, the output will be the same! | ||
With the advantage that it is generated from the code itself. | ||
Sphinx took the reStructuredText from the docstring and included it, | ||
also generating proper cross-references. | ||
|
||
You can also autogenerate documentation from other objects. For example, add | ||
the code for the ``InvalidKindError`` exception: | ||
|
||
.. code-block:: python | ||
:caption: lumache.py | ||
class InvalidKindError(Exception): | ||
"""Raised if the kind is invalid.""" | ||
pass | ||
And replace the ``.. py:exception`` directive with :rst:dir:`autoexception` | ||
as follows: | ||
|
||
.. code-block:: rst | ||
:caption: docs/source/usage.rst | ||
:emphasize-lines: 4 | ||
or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` | ||
will raise an exception. | ||
.. autoexception:: lumache.InvalidKindError | ||
And again, after running ``make html``, the output will be the same as before. | ||
|
||
Generating comprehensive API references | ||
--------------------------------------- | ||
|
||
While using ``sphinx.ext.autodoc`` makes keeping the code and the documentation | ||
in sync much easier, it still requires you to write an ``auto*`` directive | ||
for every object you want to document. Sphinx provides yet another level of | ||
automation: the :doc:`autosummary </usage/extensions/autosummary>` extension. | ||
|
||
The :rst:dir:`autosummary` directive generates documents that contain all the | ||
necessary ``autodoc`` directives. To use it, first enable the autosummary | ||
extension: | ||
|
||
.. code-block:: python | ||
:caption: docs/source/conf.py | ||
:emphasize-lines: 5 | ||
extensions = [ | ||
'sphinx.ext.duration', | ||
'sphinx.ext.doctest', | ||
'sphinx.ext.autodoc', | ||
'sphinx.ext.autosummary', | ||
] | ||
Next, create a new ``api.rst`` file with these contents: | ||
|
||
.. code-block:: rst | ||
:caption: docs/source/api.rst | ||
API | ||
=== | ||
.. autosummary:: | ||
:toctree: generated | ||
lumache | ||
Remember to include the new document in the root toctree: | ||
|
||
.. code-block:: rst | ||
:caption: docs/source/index.rst | ||
:emphasize-lines: 7 | ||
Contents | ||
-------- | ||
.. toctree:: | ||
usage | ||
api | ||
Finally, after you build the HTML documentation running ``make html``, it will | ||
contain two new pages: | ||
|
||
- ``api.html``, corresponding to ``docs/source/api.rst`` and containing a table | ||
with the objects you included in the ``autosummary`` directive (in this case, | ||
only one). | ||
- ``generated/lumache.html``, corresponding to a newly created reST file | ||
``generated/lumache.rst`` and containing a summary of members of the module, | ||
in this case one function and one exception. | ||
|
||
.. figure:: /_static/tutorial/lumache-autosummary.png | ||
:width: 80% | ||
:align: center | ||
:alt: Summary page created by autosummary | ||
|
||
Summary page created by autosummary | ||
|
||
Each of the links in the summary page will take you to the places where you | ||
originally used the corresponding ``autodoc`` directive, in this case in the | ||
``usage.rst`` document. | ||
|
||
.. note:: | ||
|
||
The generated files are based on `Jinja2 | ||
templates <https://jinja2docs.readthedocs.io/>`_ that | ||
:ref:`can be customized <autosummary-customizing-templates>`, | ||
but that is out of scope for this tutorial. |
Oops, something went wrong.