Changeset View
Changeset View
Standalone View
Standalone View
docs/contributing/sphinx.rst
.. _sphinx-gotchas: | .. _sphinx-gotchas: | ||||
Sphinx gotchas | Sphinx gotchas | ||||
============== | ============== | ||||
Here is a list of common gotchas when formatting Python docstrings for [http://www.sphinx-doc.org/en/stable/ Sphinx] and the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html Napoleon] style. | Here is a list of common gotchas when formatting Python docstrings for `Sphinx <https://www.sphinx-doc.org/en/stable/>`_ and the `Napoleon <https://www.sphinx-doc.org/en/stable/ext/napoleon.html>`_ style. | ||||
Sphinx | Sphinx | ||||
------ | ------ | ||||
Lists | Lists | ||||
+++++ | +++++ | ||||
All sorts of `lists <http://www.sphinx-doc.org/en/stable/rest.html#lists-and-quote-like-blocks>`_ | All sorts of `lists <https://www.sphinx-doc.org/en/stable/rest.html#lists-and-quote-like-blocks>`_ | ||||
require an empty line before the first bullet and after the last one, | require an empty line before the first bullet and after the last one, | ||||
to be properly interpreted as list. | to be properly interpreted as list. | ||||
No indentation is required for list elements w.r.t. surrounding text, | No indentation is required for list elements w.r.t. surrounding text, | ||||
and line continuations should be indented like the first character | and line continuations should be indented like the first character | ||||
after the bullet | after the bullet. | ||||
Bad:: | Bad:: | ||||
this is a bad example that will not be interpreted as a list | this is a bad example that will not be interpreted as a list | ||||
preceding text | preceding text | ||||
- foo | - foo | ||||
- bar | - bar | ||||
- baz | - baz | ||||
Show All 32 Lines | Good:: | ||||
- outer list continues here | - outer list continues here | ||||
surrounding text | surrounding text | ||||
Verbatim source code | Verbatim source code | ||||
++++++++++++++++++++ | ++++++++++++++++++++ | ||||
Verbatim `code blocks <http://www.sphinx-doc.org/en/stable/rest.html#source-code>`_, | Verbatim `code blocks <https://www.sphinx-doc.org/en/stable/rest.html#source-code>`_, | ||||
e.g., for code examples, requires double colon at the end of a line, | e.g., for code examples, requires double colon at the end of a line, | ||||
then an empty line, and then the code block itself, indented: | then an empty line, and then the code block itself, indented: | ||||
Bad:: | Bad:: | ||||
This does not work as there is a single column and no empty line before code: | This does not work as there is a single column and no empty line before code: | ||||
def foo(bar, baz): | def foo(bar, baz): | ||||
qux = bar + baz | qux = bar + baz | ||||
Show All 21 Lines | |||||
Good:: | Good:: | ||||
you have to instantiate the method ``def foo(bar): pass`` | you have to instantiate the method ``def foo(bar): pass`` | ||||
in order to use this abstract class | in order to use this abstract class | ||||
``**kwargs``, ``**args`` | ``**kwargs``, ``**args`` | ||||
+++++++++++++++++++++++++ | +++++++++++++++++++++++++ | ||||
`Asterisks needs to be escaped <http://www.sphinx-doc.org/en/stable/rest.html#inline-markup>`_ | `Asterisks needs to be escaped <https://www.sphinx-doc.org/en/stable/rest.html#inline-markup>`_ | ||||
to avoid capture by emphasis markup. | to avoid capture by emphasis markup. | ||||
In case of multiple adjacent asterisks, escaping the first one is enough. | In case of multiple adjacent asterisks, escaping the first one is enough. | ||||
Bad:: | Bad:: | ||||
additional **kwargs are copied in the returned dictionary | additional **kwargs are copied in the returned dictionary | ||||
Good:: | Good:: | ||||
additional \**kwargs are copied in the returned dictionary | additional \**kwargs are copied in the returned dictionary | ||||
Code cross-references | Code cross-references | ||||
+++++++++++++++++++++ | +++++++++++++++++++++ | ||||
Backquotes are not enough to cross-reference a Python entity | Backquotes are not enough to cross-reference a Python entity | ||||
(class, function, module, etc.); you need to use | (class, function, module, etc.); you need to use | ||||
`Sphinx domains <http://www.sphinx-doc.org/en/stable/domains.html>`_ for that, | `Sphinx domains <https://www.sphinx-doc.org/en/stable/domains.html>`_ for that, | ||||
and in particular the `Python domain <http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain>`_ | and in particular the `Python domain <https://www.sphinx-doc.org/en/stable/domains.html#the-python-domain>`_ | ||||
Bad:: | Bad:: | ||||
see the `do_something` function and the `swh.useless` module | see the `do_something` function and the `swh.useless` module | ||||
for more information | for more information | ||||
Good:: | Good:: | ||||
see the :func:`do_something` function and the :mod:`swh.useless` module | see the :func:`do_something` function and the :mod:`swh.useless` module | ||||
for more information | for more information | ||||
Good:: | Good:: | ||||
you can avoid a long, fully-qualified anchor setting an | you can avoid a long, fully-qualified anchor setting an | ||||
:func:`explicit label <swh.long.namespace.function>` for a link | :func:`explicit label <swh.long.namespace.function>` for a link | ||||
See also: the `list of Python roles <http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects>`_ | See also: the `list of Python roles <https://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects>`_ | ||||
that you can use to cross-reference Python objects. | that you can use to cross-reference Python objects. | ||||
Note that you can (and should) omit the <code>:py:</code> prefix, | Note that you can (and should) omit the <code>:py:</code> prefix, | ||||
as Python is the default domain. | as Python is the default domain. | ||||
Note also that when building Sphinx documentation | Note also that when building Sphinx documentation | ||||
for individual Software Heritage modules in isolation, | for individual Software Heritage modules in isolation, | ||||
cross-references to other modules will *not* be resolvable. | cross-references to other modules will *not* be resolvable. | ||||
But they will be resolvable when building the unified documentation | But they will be resolvable when building the unified documentation | ||||
from ``swh-docs`` | from ``swh-docs`` | ||||
Napoleon | Napoleon | ||||
-------- | -------- | ||||
Docstring sections | Docstring sections | ||||
++++++++++++++++++ | ++++++++++++++++++ | ||||
See the `list of docstring sections <http://www.sphinx-doc.org/en/stable/ext/napoleon.html#docstring-sections>`_ | See the `list of docstring sections <https://www.sphinx-doc.org/en/stable/ext/napoleon.html#docstring-sections>`_ | ||||
supported by Napoleon. | supported by Napoleon. | ||||
Everything else will *not* be typeset with a dedicated heading, | Everything else will *not* be typeset with a dedicated heading, | ||||
you will have to do so explicitly using reStructuredText markup. | you will have to do so explicitly using reStructuredText markup. | ||||
Args | Args | ||||
++++ | ++++ | ||||
Entries in Args section do *not* start with bullets, but just with argument names (as any other Napoleon section). | Entries in Args section do *not* start with bullets, but just with argument names (as any other Napoleon section). | ||||
▲ Show 20 Lines • Show All 72 Lines • Show Last 20 Lines |