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?

You could 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://stackoverflow.com/a/12087750/407651. — mzjn, May 15 '17 at 15:11
Yes that works, thank you! New version can be seen [here](http://pandapower.readthedocs.io/en/develop/elements/load.html#create-function). Seems like a valid answer, is there a reason you submitted this as comment? — lthurner, May 15 '17 at 17:13

score 0 · Accepted Answer · answered May 15 '17 at 18:24

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

    ...

    """

A long signature can actually occupy several lines (it works without line continuation characters). — mzjn, May 16 '17 at 07:35

Sphinx autodoc with parameter from a mocked module on readthedocs

1 Answers1