It can be convenient to run the global swh documentation in the
current venv instead of using tox (notably to save time by skipping
dependencies installation).

It looks like the Makefile in docs folder was not really maintained
regarding that kind of documentation build so fix it in order to
restore local build.

This would warrant a more thorough guide, but I'm not the best person to
write such a guide, and this is better than having nothing.

Sphinx started to crash recently because of that not needed file
processed by apidoc.

Related to T4324

To explicit how to use the generated credentials.

Related to T4259

It got displayed again after reintegration of custom CSS rules but
it should have been removed since a while.

Add landing page of listersrs high-level documentation displaying
available ones in a table with the following column:

  - logo and name of the lister linking to its specific documentation

  - related links: source code, developer doc, development activity

  - current status: production, staging or development

  - link to related grant if any

Create one rst file per lister to further document.

Related to T3117

Add landing page of loaders high-level documentation displaying
available ones in a table with the following column:

  - logo and name of the loader linking to its specific documentation

  - related links: source code, developer doc, development activity

  - current status: production, staging or development

  - link to related grant if any

Create one rst file per loader to further document.

Related to T3117

Encountered issues have been fixed so we can remove the pinning of sphinx.

It is a common practice to open an external link in a new browser
tab so process external links with javascript when a documentation
page got loaded to enforce such behavior.

Corresponding RST document has been renamed to uri-scheme-swhids.rst
so add a redirection for URL backward compatibility.

With recent enough versions of setuptools/setuptools-scm, the pip
dependency resolver is now capable of sorting out our full dependency
tree. We can just install all packages at once (which does the
dependency resolution step once).

To speed up the process even more, inline the few "build" (setup.py)
dependencies to allow disabling build isolation (which creates a new
venv and installs setuptools-scm in it for every single package).

That hook can be frustrating as it can discard a long commit message
if it finds a typo in it so better removing it.

black is considered stable since release 22.1.0 and the version
we are currently using is quite outdated and not compatible with
click 8.1.0, so it is time to bump it to its latest stable release.

Please note that E501 pycodestyle warning related to line length
is replaced by B950 one from flake8-bugbear as recommended by black.
https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length

Related to T3922

to use aptitude as dep resolver when needed and add backports in given cli examples

Related to T4102

Related to T4105

This nests the historical roadmap under a specific roadmap/index
toctree, so that they don't all show up in the sidebar.

This fixes the build [1]

[1] https://jenkins.softwareheritage.org/job/DDOC/job/dev/1139/console

[1] https://jenkins.softwareheritage.org/job/DDOC/job/dev/1135/console

Without this, the actual documentation build will fail once a new package is
incompletely installed.