Sphinx autodoc，其参数来自 readthedocs 上的模拟模块

Question

我们正在使用 readthedocs 来记录我们的开源项目 pandapower。

由于 pandapower 依赖于无法在 rtd 上构建的 numpy 和其他 C 库，我们使用 autodoc_mock_imports 参数为这些库创建模拟导入。这在一般情况下效果很好，但会导致将 np.nan 作为默认参数的函数的 autodoc 出现问题，例如代码中的 here. The default value e.g. for the sn_kva parameter is np.nan (see here，但由于 numpy 作为模拟模块导入，它显示作为 "sphinx.ext.autodoc._MockModule object"。

有人知道可以避免这种情况吗？

Answer 1

提供所需的签名作为文档字符串的第一行。然后 Sphinx 将使用它作为输出中的签名。参见 http://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autodoc_docstring_signature。

在您的例子中，函数的第一行如下所示：

def create_load(net, bus, p_kw, q_kvar=0, const_z_percent=0, const_i_percent=0, sn_kva=nan,
            name=None, scaling=1., index=None,
            in_service=True, type=None, max_p_kw=nan, min_p_kw=nan,
            max_q_kvar=nan, min_q_kvar=nan, controllable=nan):
    """
    create_load(net, bus, p_kw, q_kvar=0, const_z_percent=0, const_i_percent=0, sn_kva=nan,
                name=None, scaling=1.0, index=None,
                in_service=True, type=None, max_p_kw=nan, min_p_kw=nan,
                max_q_kvar=nan, min_q_kvar=nan, controllable=nan)

    Adds one load in table net["load"].

    ...

    """

Sphinx autodoc，其参数来自 readthedocs 上的模拟模块

Sphinx autodoc with parameter from a mocked module on readthedocs

python-sphinx

autodoc

read-the-docs