suggested by @douardda

It simplifies documentation build configuration as the include path
might change depending on where the sphinx-build command is invoked.

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

Ref. swh/infra/sysadm-environment#4724

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.

vlorentz authored 2 years ago and Antoine R. Dumont committed 2 years ago

It's no longer built for it.

Document new metrics on outgoing API requests

See merge request swh/devel/swh-docs!274

Document statsd metrics and link to dashboards

See merge request swh/devel/swh-docs!270

Related to T4717

Add the standalone_package_doc sphinx tag when building standalone
documentation of a swh package.

It enables to conditionnally include content in package documentation,
like indices and tables for instance.

Related to T4496

Related to https://gitlab.softwareheritage.org/infra/sysadm-environment/-/issues/4675

Related to https://gitlab.softwareheritage.org/infra/sysadm-environment/-/issues/4674

Django settings modules were no longer filtered out from apidoc
processing when building standalone swh package documentation.

Regression introduced in 2f5cbf0c as tox files use SPHINXOPTS environment
variable to add custom sphinx options (like -W).

Thanks to douardda for noticing.

sphinx-design is an iteration on sphinx-panels and intends to replace
it. It offers more interesting web components like cards which we will
be happy to use for the landing page.

Migration tips are available at:
https://sphinx-design.readthedocs.io/en/rtd-theme/get_started.html#migrating-from-sphinx-panels

Since this got improved using an intermediary build-deps container.

This bootstraps the usual commands related to topics management.

Previously the file patterns that sphinx-apidoc must exclude, stored
in the APIDOC_EXCLUDES variables, were expanded by the shell before
executing the tool resulting in a really long list of files to exclude.
Each time a file was processed by sphinx-apidoc, its path was compared
against that long list of files which was significantly slowing down
the apidoc generation process.

So ensure file exclude patterns are quoted to avoid shell expansion
and greatly speedup sphinx-apidoc execution.