Differential D5784 Diff 21696 docs/contributing/sphinx.rst

Changeset 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