Sphinx autodoc with parameter from a mocked module on readthedocs

Question

We are using readthedocs to document our open source project pandapower.

Since pandapower has dependencies to numpy and other C libraries that can't be built on rtd, we use the autodoc_mock_imports parameter to create mock imports for these libraries. This works great in general, but causes problems in the autodoc of functions that have np.nan as default parameters, for example here. The default value e.g. for the sn_kva parameter is np.nan (see here in the code), but since numpy is imported as a mock module, it shows up as "sphinx.ext.autodoc._MockModule object".

Does anyone know of a possibility to avoid this?

Answer 1

Provide the wanted signature as the very first line of the docstring. Sphinx will then use that as the signature in the output. See http://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autodoc_docstring_signature.

In your case, the first lines of the function would look like this:

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

    ...

    """