Even if our `tox.ini` is compatible with tox 3, the command line
format changed with tox 4. For consistency in layout, usage and
documentation, it seems best to update requirements to version 4.

See: https://tox.wiki/en/latest/upgrading.html#updating-usage-with-e

These changes allow to build all SWH documentations (developmment, system
administration and user) using a single sphinx-build command, meaning they
are now merged into a single one with shared index of references.

Development documentation is now rooted to docs/devel, user one to docs/user
and sysadmin one to docs/sysadm so a good amount of files were moved.

A couple of configuration files and makefiles were updated to reflect that change
and the building / cleaning processes were made more reliable.

Calling make in root directory of swh-docs will execute the development build
of the documentation in a tox environment while calling make in docs folder
will use the current virtualenv.

It remains possible to build each documentation in a standalone way by
calling make in their root directory.

Closes #4496

Some deprecated tox 3.x features have been removed in tox 4.x
and some install behaviors changed between the two versions.

So add tox 4.x support while keeping tox >= 3.7 compatibility.

- pre-commit from 4.1.0 to 4.3.0,
- codespell from 2.2.1 to 2.2.2,
- black from 22.3.0 to 22.10.0 and
- flake8 from 4.0.1 to 5.0.4. Also freeze flake8 dependencies.

Also change flake8's repo config to github (the gitlab mirror
being outdated).

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

This also adds a redirection from the old path "users" to the new one "user".

Related to T3650

Related to T3154

Related to T3388

And add environment variable SPHINXOPTCOLOR to disable it on Jenkins

The new pip resolver ends up backtracking numerous packages when
installing all depencies in a single pip command but this is
terribly slow and long to execute.

A workaround is to install each swh package one at a time by
executing pip multiple times, no backtracking happens in that
case and it reduces considerably the overall installation time.

Another advantage of proceeding like this is that it ensures each
swh package will be installed in development mode.

Also increase tox verbosity when calling make to have some feeback
of what it is doing.

This reverts commit b5d50d89.

This only worked because I have a local postgresql on which I'm superuser,
apparently.

This reverts commit 457c9f64.

This commit removed both the source copy step and the actual linking of the docs
sources. Turns out that the latter is "somewhat" necessary for a proper doc
build.

Close T2386

by installing swh packages in standard (non-editable) mode, so we have an
easy to specify swh/ directory in which all the swh packages are installed.

The main drawback of this solution is we loose the possibility of rebuilding
the doc (in tox) while editing a package's documentation without rebuilding
the tox env (i.e. using tox -r). But IMHO this usage has never been
adpoted by anyone, so it's much simpler that way.

to prevent weird race condition when both requirements-swh.txt and
requirements-swh-dev.txt are added as requirements.

This is needed to make:

  tox -e sphinx-dev

work as expected, ie. with swh packages installed from sources rather than
from pypi.

This will allow the CI to run the building job with sphinx options like
`-W` (aka "turn warnings into errors").

that builds the doc using source code repos located one directory above
instead of published versions of swh subpackages.

Related to T1330.

- back to assets only building in each package
- run sphinx-autodoc on the whole swh package at once

we do not really need a local standalone buildable sphinx project in each swh
subpackage, so running a full 'make html' in each of them is not required any
more.

Since we want to build the doc at once instead of building each swh subpackage
independantly, we need to run apidoc on the whole swh package.

This is done by actually running the apidoc on the pip installed swh
packages instead of the source repositories, since sphinx-apidoc does
not seem to support multiple MODULE_PATH as cmdline argument.

So it's best to use tox to build the doc.

Related to T1330.