I'm documenting my Python package using Sphinx. But I've come across several warnings I have no idea, what to do about. All of them are occurring in my module-level docstrings, not inside of classes or methods.
When trying to build my documentation on ReadTheDocs I'm getting the following error:
/home/docs/checkouts/readthedocs.org/user_builds/project/checkouts/latest/project/vqe_optimization.py:docstring of project.optimization:1: WARNING: Field list ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/project/checkouts/latest/project/optimization.py:docstring of project.vqe_optimization:1: WARNING: Field list ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/project/checkouts/latest/project/optimization.py:docstring of project.vqe_optimization:3: WARNING: Definition list ends without a blank line; unexpected unindent.
I'm completely puzzled by this, as my docstring looks like this:
"""Module containing the core Project engine.
Core Project module comprising implementation of the core Project solver
class together with optimizer interfaces etc. The module aims to contain
all the logic behind Project solution, which is not directly connected to
the properties of the electronic structure problem being solved or to the
properties of logically-independent circuits
like an initial orthogonal set or an ansatz.
"""
Here I'm completely puzzled... What is incorrect at the first and third line?
In my conf.py I'm using these extensions:
extensions = [
'sphinx.ext.viewcode',
'sphinx.ext.napoleon',
'myst_parser',
'nbsphinx',
'nbsphinx_link',
'sphinx.ext.autodoc'
]
The link to my project's build log is here: https://readthedocs.org/api/v2/build/25619818.txt
When you have a field with a description of multiple lines in a docstring, then you need to indent the second and subsequent lines.
In the following example, :param circuit: is the field, followed by its multiple line description.
def get_evaluation_func(self, circuit: QuantumCircuit) -> Callable:
"""
Obtain evaluation function (i.e. a function returning expectation
values when provided parameters).
:param circuit: Quantum circuit representing a parametrized state
vector w.r.t. which the expectation values
are computed.
:return: Evaluation function
"""
...should be...
def get_evaluation_func(self, circuit: QuantumCircuit) -> Callable:
"""
Obtain evaluation function (i.e. a function returning expectation
values when provided parameters).
:param circuit: Quantum circuit representing a parametrized state
vector w.r.t. which the expectation values are computed.
:return: Evaluation function
"""
The warning messages that Sphinx emits due to malformed docstrings can be misleading, indicating the wrong line number.