Related to T3374

There is no reason to filter out these warnings only in tox builds
as the issue comes from upstream httpdomain not in sync with latest
sphinx API.

It also enables to unstuck swh-web and swh-docs builds on Jenkins.

Since the release of sphinx 4.1, a new warning related to httpdomain
extension appeared when buidling swh-web documentation.

It is not critical and is due to httpdomain not in sync with latest
changes in sphinx, so filter out that warning as it makes sphinx
builds fail for swh-web on Jenkins.

The following document demonstrates how to create a new swh package in the current swh
phabricator instance and reference it so the Continuous Integration (CI) is able to
build the new module.

Related to T3179

So it's integrated in the build.

Related to T2845

It's not working with the default plantuml version installed
with debian buster (1.2018.13)

Similarly to what the previous commit did to the developer doc

The FAQ was put in a single file in faq/faq.rst as a hack, using
multiple top-level headers in the same file to make them appear
in the global TOC.

With this change, the TOC is moved to the index.rst file, with
a single top-level header, and uses a local TOC instead, as it
should be.

Additionally, this removed the manually-written TOC in the main
index to use an auto-generated one.

Related to T3388

This opens the users faq we short-listed during the documentation sprint. Question are
regrouped under a specific category.

Categories are listed from the main page and from the left menu.

Related to T3388

This opens the developers faq we short-listed during the documentation sprint. Question
are regrouped under a specific category.

Categories are listed from the main page and from the left menu.

Related to T3119

Related to T3388

Related to T3119

Previous values did not prevent sphinx-apidoc to walk the content
of these directories resulting in really long processing when
directories contain a lof of entries (node_modules for instance).

fix the jenkins build (dev)

Related to T3203

initiate an infrastructure section and a network sub-section

Remark: the png of the plantuml diagram is committed because
the svg in not correctly rendered

Related to T3203

This fixes an import error during sphinx-apidoc processing.

It's needed by the ci to be able to reference the api links

Related to T3307

The first two redirect, the last one is broken.

As it was, it was unclear that it linked to the documentation of internal
Python module, instead of the public HTTP API.

Phabricator short code is used as folder name instead of project name
in that case.

Related to T3258

Enable to build the local documentation of each swh package using a
dedicated tox environment.

In order to check for possibly introduced sphinx warnings in the
documentation sources, the documentation is built with the -W option
of sphinx-build.

As some references located in scopes external to the processed
package would not be resolved, related sphinx warnings are
suppressed to allow the doc build to succeed anyway.

Besides the errors related to references that can only be checked
when building the full documentation, all other sphinx errors
should be caught.

Related to T3258

For some reason, neither was included, even though 'autoclass_content'
should default to 'class'.
Anyway, there is no harm in including both.

Software Heritage uses Django in several packages: swh-auth, swh-deposit
and swh-web.

When building global or local package documentation, the environment
variable DJANGO_SETTINGS_MODULE must be set to the adequate settings
module in order to avoid errors with sphinx autodoc processing.

Previous approach was merging swh-deposit and swh-web django settings
but it did not prevent all autodoc errors due to some missing or
unexpected django setting value.

New approach force reset Django settings according to the next rst
document to read by sphinx. This ensures adequate django settings
will be set for each swh packages before processing apidoc generated
rst files.

It also enables to not depend on swh-deposit and swh-web for building
a local package documentation.

Related to T3258

It enables to not depend on swh-web to build standalone swh package
documentation, plus these sphinx features could be reused in other
package documentation.

Related to T3258

- add the scheduler journal client
- remove the indexer journal client (for clarity)
- remove indexer workers (for clarity)
- add a postgresql db attached to the web app

Closes T3229.

It seems to be misunderstood by most people when they start out.

It is now required for swh-web frontend development.

And add environment variable SPHINXOPTCOLOR to disable it on Jenkins

The command is not always installed by default, for instance in the
debian:buster docker image.