Search code examples
pythonpython-sphinxnumpydocsphinx-napoleon

Using array-like as a type in napoleon without warning

I have a project with some functions documented in the napoleon numpy style. In the spirit of numpyness, I have a bunch of function arguments that are of the class array-like. Here is an example:

def foo(x, y):
    """
    Foo the arguments together to make a bar.

    Parameters
    ----------
    x : array-like
        This is an argument.
    y : array-like
        I like it, give me another!

    Returns
    -------
    bar : numpy.ndarray
        Works every time
    """
    pass

This works just fine, and the type is included in the output without a link:

generated

The problem is that I get a warning on every line of every function that has this:

/.../my_project/my_module.py:docstring of my_project.my_module.foo:: WARNING: py:class reference target not found: array-like
/.../my_project/my_module.py:docstring of my_project.my_module.foo:: WARNING: py:class reference target not found: array-like

I am fairly convinced that there is some solution. It appears that PR #7690 addressed this somehow, but I can't find a meaningful reference "preprocessing" anywhere in the napoleon or broader sphinx documentation.

So how do I get rid of the warning?

Solution

  • Digging through the PR, I found where to look: the napoleon_type_aliases configuration item allows you to set up a mapping for things like array-like, dict-like, etc. In this particular case, adding the following to conf.py did the trick:

    napoleon_use_param = True
napoleon_type_aliases = {
    'array-like': ':term:`array-like <array_like>`',
    'array_like': ':term:`array_like`',
}

    napoleon_use_param has to be True for this to work. It's documented as defaulting to True, but somewhere along the way in my setup, it got unset. It never hurts to be extra safe.

    To link to the array_like term on the numpy site, the intersphinx extension must be enabled, and intersphinx_mapping in conf.py must link to numpy:

    intersphinx_mapping = {
    ...
    'numpy': ('https://numpy.org/doc/stable/', None),
    ...
}