Pin numpydoc to avoid doubly-escaped *

[gforsyth]

Similar to dask/dask#5961, recent changes to numpydoc lead to function
signatures displayed using autosummary to have doubly-escaped *s.

This commit swaps out numpydoc in favor of napoleon -- there are a
couple of benefits:

• no more double-escaped function signatures
• one less dependency for docs (napoleon is shipped with sphinx)

I've added a make target to automatically generate API docs using
sphinx-apidoc but this isn't required for autosummary compatibility.
It can always be added as a requirement of the html target at a later
time.

[gforsyth]

@jrbourbeau this may be a better solution than the one I pushed up to dask/dask, but we can also pin numpydoc here, too, if that's preferred.

[jrbourbeau]

Thanks @gforsyth! I'm new to napoleon. It looks like the styling of API docs is slight different (not an issue IMO). For example, with numpydoc:

with napoleon:

It also looks like there may be support for using type annotations in generated API docs, which would be great. Do you know of other difference between numpydoc and napoleon?

Also cc @jsignell who has been working on our docs recently and @jcrist who (may?) have starting using napoleon in other projects

[gforsyth]

Do you know of other difference between numpydoc and napoleon?

Just that they're roughly equivalent. numpydoc supports adding ::plot directives which I think is then also used by extensions that autogenerate example galleries, but I don't think that's used in the dask docs anywhere.

I also don't have a preference on styling, although it should probably match across all dask projects -- if folks are ok with the general styling change I can swap this out in the other repos, too.

[jcrist]

I've used both in the past. In general both seem to work fine, but they style things differently. Agree with Gil that it'd be good to standardize this across projects, no strong preferences either way.

[jsignell]

This change seems reasonable to me. No strong feelings on the style change.

[jrbourbeau]

Sorry for the delayed reply here. I think I'd rather stick with numpydoc for the time being. Not all of our docstrings follow the official numpydoc style for their Returns sections and so both numpydoc and napoleon outputs aren't properly formatted. However, napoleon makes things bulleted which looks a little more off to me than the numpydoc styling. For example:

Napoleon:

Numpydoc:

We could also reformat our docstrings, which could be done in a future PR

[gforsyth]

Good with me, I don't have strong opinions on this either way. I'll change this PR to pin numpydoc instead -- also followed up in numpy/numpydoc#221 which should fix the issue in numpydoc with the double-escapes.

[gforsyth]

Hey @jrbourbeau -- updated this to pin numpydoc instead and fixed a few small nits.

Small changes to avoid a sphinx timeout looking for an intersphinx inventory, and a fixed a misformatted code-block

[jrbourbeau]

Thanks @gforsyth!

[jrbourbeau]

Nice 😎

[jsignell]

Good catch @jrbourbeau! Do we need a follow on issue to coerce all the docstrings to numpydoc style?

[jrbourbeau]

I opened up #3578 for updating the docstring style