📚⬆️ UPDATE: sphinx v4 (+ sphinx extensions)

[chrisjsewell]

This PR updates sphinx to version 4, as well as updating docutils, pygments, pydata-sphinx-theme, and sphinx-copybutton.

A key issue for this upgrade, was that sphinx.ext.autodoc reads classes/functions from both modules and also from __all__.
In sphinx 3 this was actually failing silently, by duplicating all the API documentation for these objects, for example:

• https://aiida.readthedocs.io/projects/aiida-core/en/v1.6.7/reference/apidoc/aiida.orm.html#aiida.orm.Computer
• https://aiida.readthedocs.io/projects/aiida-core/en/v1.6.7/reference/apidoc/aiida.orm.html#aiida.orm.computers.Computer

In sphinx 4, this now emits a duplicate object description warning.

To fix this, the ignore-module-all flag has been added to all autodoc directives.
Then, to overcome the fact that we would still like to refer to the top-level module paths (e.g. aiida.orm.Computer rather than aiida.orm.computers.Computer), some code has been added in conf.py, to specify these aliases.

Note, I think long-term, it might just be better to remove the use of sphinx-apidoc, and specify the modules to document explicitly, using only their __all__, i.e. only create API documentation for public APIs.
This is a bigger change though (plus non-essential) so I'd push that back to a later date.

You'll also see that most of the nitpick-exceptions have now been removed 😄

[chrisjsewell]

Note, this also removes the need to pin markupsafe, since sphinx 4.1 does not pin jinja2: sphinx-doc/sphinx@85f5887

[sphuber]

Just two minor comments

[sphuber]

Hmm, this also includes all our custom ParameterType implementations in aiida.cmdline.params.types. Don't think it is the worst, but is there a way we can exclude those?

[chrisjsewell]

This just stops a warning from being emitted if it can't resolve the reference, it won't stop the reference from being resolved if present

[sphuber]

Yeah I get that, but if there is warning related to our param types, that is probably because there is a real problem, and this way it will go unnoticed.

[chrisjsewell]

Eurgh, unless you are literally going to be using :py:obj:`aiida.cmdline.params.types.WrongType` in the documentation, or a docstring, I don't think it's going to be a big problem. Obviously, actual typing errors should be tested by mypy

[sphuber]

But that is the whole point of these warnings, to warn you if you (by accident) type a wrong resource, for example a typo.

[chrisjsewell]

There are literally no sphinx references to ParamType anywhere in the documentation/docstrings, but anyhow I've removed this and reinstated a lovely long nitpick_exceptions list.

[sphuber]

Any reason to have ~=4.0 here but ~=4.1 in the docs extra?

[chrisjsewell]

nitpick_ignore_regex was only introduced in 4.1, added for our docs build, but for testing the aiida sphinx extension, it is only sphinx 4 that is needed (it still actually works for sphinx 3, but there is a change in the AST, when regression testing the output)