That's pretty big, because it includes these modules' `.git` and `.tox`,
which sums to gigabytes.

Improving the postactivate hook to work both for zsh/bash users

- a very basic docker-based quick start,
- a more advanced developer setup guide (using mixed docker/venv install),
- the original manual setup guide.

Closes T1341

Without this dependency, the pifpaf tests won't execute. They will
fail with a cryptic error.

That cryptic error message is currently fixed by pifpaf's author. It's
pending in a PR and should soon land.

Related P341
Related https://github.com/jd/pifpaf/issues/108
Related https://github.com/jd/pifpaf/pull/119

- do not silence sphinx CLI invocations (it's bad for logs)
- avoid $(apidoc_dep) variable (it doesn't exist for any other *-stamp)

Reviewers: #reviewers, ardumont

Reviewed By: #reviewers, ardumont

Differential Revision: https://forge.softwareheritage.org/D880

Depends on D834

Remove the depth-one tree in py-deps-swh.svg doc as the root.

swh-web depends on swh-indexer so we must ensure swh-indexer is installed
first (otherwise the last pubished version is used instead of the one
from the sources).

Reviewers: #reviewers, douardda

Reviewed By: #reviewers, douardda

Differential Revision: https://forge.softwareheritage.org/D744

Reviewers: #reviewers, douardda

Reviewed By: #reviewers, douardda

Differential Revision: https://forge.softwareheritage.org/D743

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").

this aims at eliminating a warning generated by sphinx-build on swh-web's
index, due to the presence of an explicit link to the http-routingtable.html
file (which does not exists at that time, thus generated a warning).

This should be killed once

  https://github.com/sphinx-contrib/httpdomain/pull/19

is accepted and released.

and add swh-storage[listener] dep for the sake of completeness while
building the doc.

the env var setup and django.setup() needs to be done only once.

so we have more than just the 's' index entry 's' in there.

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.

so that we can have some generic substitutions which can be used consistently
in the doc.

even though there is no test in this package.

It breaks the index generation in each swh-* package.

and thus prevent sphinx from complaining about rst files not being included in
a toctree without having to insert :orphan: everywhere.

so we do not build each swh-* twice with unavaoidable sphinx wrnings when
building each repo locally.