ReadTheDocs Sphinx：警告：字段列表结束时没有空行；意外的未缩进

Question

我正在使用 Sphinx 记录我的 Python 包。但我遇到了几个我不知道该怎么办的警告。所有这些都发生在我的模块级文档字符串中，而不是在类或方法内部。

当尝试在 ReadTheDocs 上构建我的文档时，我收到以下错误：

/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.

我对此完全困惑，因为我的文档字符串如下所示：

"""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.
"""

这里我完全困惑了...第一行和第三行哪里不正确？

在我的

conf.py

中，我正在使用这些扩展：

extensions = [
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'myst_parser',
    'nbsphinx',
    'nbsphinx_link',
    'sphinx.ext.autodoc'
]

我的项目构建日志的链接位于：https://readthedocs.org/api/v2/build/25619818.txt

Answer 1

当文档字符串中有一个包含多行描述的字段时，您需要缩进第二行和后续行。

在以下示例中，

:param circuit:

是字段，后跟其多行描述。

    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
        """

...应该是...

    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
        """