Use napoleon instead of numpydoc with sphinx

[leouieda]

The napoleon sphinx extension renders the numpy docstrings better than
numpydoc and works with newer versions of sphinx. This way, we upgrade
to a newer sphinx which works better with the readthedocs theme. Older
sphinx is also a problem for Python 3.8 packages on conda-forge.

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

[weiji14]

This napolean thing looks amazing! It's definitely a step forward, but we'll need to make our docstrings consistent for this. I much prefer having the long alias name before the short alias (i.e. longalias (L)), but I'm not sure if this can be configured? Currently the short alias comes before the recommended long ones, see examples below:

https://pygmt-d8guesy9o.now.sh/api/generated/pygmt.Figure.contour.html

https://pygmt-d8guesy9o.now.sh/api/generated/pygmt.makecpt.html

[leouieda]

@weiji14 that is not really a problem with napoleon but a problem with our docstring formatting (and argument parsing in general). We shouldn't be putting the alias or option in parenthesis as that isn't following the numpy standard. So we can keep this as is and work on a fix that will put us back in the standard.

I'm working on a refactor of the argument handling mechanisms. The main problem is that we're using **kwargs which means that tab completion doesn't work. I'm thinking of ditching the single character arguments all together and instead having explicitly set long form arguments for all functions (this would mean getting rid of the alias mechanism). It'll be less confusing and easier to maintain since the wrapper code with functions in functions in functions is a bit hard to read.

[CsatiZoltan]

@leouieda Hi. Sorry for the possible off-topic, but how could you achieve clickable types with napoleon in the Parameters section of the docstrings ? E.g. in this function, you did not use any explicit markup for the pad argument, and still the type int brings us to the Python documentation. I checked the conf.py file but couldn't figure out what makes it possible. I think, I properly set up Intersphinx in the conf.py file of my project because explicit links do work.