From 0e55968dfa67d4a3518c84f3d36fc16e3e3f0795 Mon Sep 17 00:00:00 2001
From: Antoine Lambert <anlambert@softwareheritage.org>
Date: Thu, 17 Nov 2022 14:49:35 +0100
Subject: [PATCH] docs: Merge all documentations into a single one

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
---
 Makefile.local                                |   2 +
 docs/.gitignore                               |   2 +-
 docs/Makefile                                 |  92 +++----
 docs/_templates/layout.html                   |  21 --
 docs/bin/ln-sphinx-subprojects                |  35 ---
 docs/devel/Makefile                           |  66 +++++
 docs/{ => devel}/api-reference.rst            |   0
 docs/{ => devel}/architecture.rst             |   0
 docs/{ => devel}/architecture/index.rst       |   0
 docs/{ => devel}/architecture/metadata.rst    |   0
 docs/{ => devel}/architecture/overview.rst    |   0
 docs/{ => devel}/archive-changelog.rst        |   0
 .../bin/copy-and-fix-subprojects-indices      |   0
 docs/devel/bin/ln-sphinx-subprojects          |  39 +++
 docs/{ => devel}/bin/py-depgraph              |   0
 docs/devel/conf.py                            |   1 +
 docs/{ => devel}/contributing/code-review.rst |   0
 .../contributing/git-style-guide.rst          |   0
 docs/{ => devel}/contributing/index.rst       |   0
 docs/{ => devel}/contributing/phabricator.rst |   0
 .../contributing/python-style-guide.rst       |   0
 docs/{ => devel}/contributing/sphinx.rst      |   0
 .../tutorial-docs-contribution.rst            |   0
 docs/{ => devel}/developer-setup.rst          |   0
 docs/{ => devel}/faq/index.rst                |   0
 docs/{ => devel}/getting-started.rst          |   0
 docs/{ => devel}/getting-started/api.rst      |   0
 docs/{ => devel}/getting-started/index.rst    |   0
 docs/devel/getting-started/using-docker.rst   |   3 +
 docs/{ => devel}/glossary.rst                 |   0
 docs/{ => devel}/images/.gitignore            |   0
 docs/{ => devel}/images/Makefile              |   8 +-
 .../images/architecture_diagram.dot           |   0
 docs/{ => devel}/images/elasticsearch.dot     |   0
 .../images/general-architecture.svg           |   0
 .../lister-loader-scheduling-architecture.svg |   0
 docs/{ => devel}/images/tasks-git-loader.uml  |   0
 docs/{ => devel}/images/tasks-lister.uml      |   0
 docs/devel/index.rst                          | 243 ++++++++++++++++++
 docs/{ => devel}/infrastructure.rst           |   0
 docs/{ => devel}/journal.rst                  |   0
 docs/{ => devel}/keycloak.rst                 |   0
 docs/{ => devel}/mirror.rst                   |   0
 docs/{ => devel}/roadmap/index.rst            |   0
 docs/{ => devel}/roadmap/roadmap-2021.rst     |   0
 docs/{ => devel}/roadmap/roadmap-2022.rst     |   0
 docs/{ => devel}/services.txt                 |   0
 docs/{ => devel}/statsd.rst                   |   0
 docs/{ => devel}/swh-loader.rst               |   0
 .../{ => devel}/tutorials/add-new-package.rst |   0
 docs/{ => devel}/tutorials/index.rst          |   0
 .../tutorials/issue-debugging-monitoring.md   |   0
 docs/{ => devel}/tutorials/testing.rst        |   0
 docs/getting-started/using-docker.rst         |   3 -
 docs/index.rst                                | 239 +----------------
 {sysadm => docs/sysadm}/.gitignore            |   0
 {sysadm => docs/sysadm}/Makefile              |  10 +-
 {sysadm => docs/sysadm}/_static               |   0
 {sysadm => docs/sysadm}/conf.py               |   0
 .../sysadm}/data-silos/cassandra/index.rst    |   0
 .../data-silos/cassandra/installation.rst     |   0
 .../data-silos/elasticsearch/index.rst        |   0
 {sysadm => docs/sysadm}/data-silos/index.rst  |   0
 .../sysadm}/data-silos/kafka/index.rst        |   0
 .../data-silos/kafka/manage-topics.rst        |   0
 .../sysadm}/data-silos/postgresql/backup.rst  |   0
 .../data-silos/postgresql/howto-connect.rst   |   0
 .../sysadm}/data-silos/postgresql/index.rst   |   0
 {sysadm => docs/sysadm}/deployment/argocd.rst |   0
 .../sysadm}/deployment/deploy-lister.rst      |   0
 .../deployment/deployment-environments.rst    |   0
 .../deployment/howto-debian-packaging.rst     |   0
 .../howto-process-add-forge-now-requests.rst  |   0
 {sysadm => docs/sysadm}/deployment/index.rst  |   0
 .../sysadm}/deployment/jenkins.rst            |   0
 .../deployment/storage-database-migration.rst |   0
 .../deployment/upgrade-swh-service.rst        |   0
 .../sysadm}/getting-started/index.rst         |   0
 .../getting-started/setup-repositories.rst    |   0
 {sysadm => docs/sysadm}/images/.gitignore     |   0
 {sysadm => docs/sysadm}/images/Makefile       |   0
 .../sysadm}/images/gitlab-infrastructure.png  | Bin
 .../network/carp_maintenance.png              | Bin
 .../network/check_for_upgrade.png             | Bin
 .../infrastructure/network/proceed_update.png | Bin
 .../network/reactivate_carp.png               | Bin
 .../images/infrastructure/network/sync.png    | Bin
 .../images/jenkins/300px-build-button.png     | Bin
 .../sysadm}/images/jenkins/300px-replay.png   | Bin
 .../jenkins/300px-restart-from-stage.png      | Bin
 .../sysadm}/images/jenkins/diff-report.png    | Bin
 .../images/jenkins/revision-report.png        | Bin
 .../sysadm}/images/keycloak_add_user_01.jpg   | Bin
 .../sysadm}/images/keycloak_add_user_02.jpg   | Bin
 .../sysadm}/images/keycloak_add_user_03.jpg   | Bin
 .../keycloak_add_user_permission_01.jpg       | Bin
 .../keycloak_add_user_permission_02.jpg       | Bin
 .../keycloak_add_user_permission_03.jpg       | Bin
 .../keycloak_add_user_permission_04.jpg       | Bin
 .../sysadm}/images/mirror-architecture.svg    |   0
 {sysadm => docs/sysadm}/images/network.uml    |   0
 .../openvpn/nm-openvpn-advanced-general.png   | Bin
 .../openvpn/nm-openvpn-advanced-security.png  | Bin
 .../openvpn/nm-openvpn-advanced-tls-auth.png  | Bin
 .../images/openvpn/nm-openvpn-base.png        | Bin
 .../images/openvpn/nm-openvpn-routes.png      | Bin
 .../images/openvpn/vpn-csr-certificate.png    | Bin
 .../images/openvpn/vpn-csr-signing.png        | Bin
 .../sysadm}/images/openvpn/vpn-ctrl-list.png  | Bin
 .../images/openvpn/vpn-main-trust-page.png    | Bin
 .../sysadm}/images/staging-environment.uml    |   0
 {sysadm => docs/sysadm}/index.rst             |  15 +-
 .../how-to-manage-tools-upgrades.rst          |   2 +-
 .../how-to-new-service-backup.rst             |   0
 .../sysadm}/life-cycle-management/index.rst   |   0
 {sysadm => docs/sysadm}/make.bat              |   0
 .../sysadm}/mirror-operations/deploy.rst      |   0
 .../sysadm}/mirror-operations/docker.rst      |   4 +-
 .../sysadm}/mirror-operations/index.rst       |   0
 .../sysadm}/mirror-operations/monitor.rst     |   0
 .../sysadm}/mirror-operations/onboard.rst     |   0
 .../sysadm}/mirror-operations/planning.rst    |   0
 .../sysadm}/network-architecture/dns.rst      |   0
 ...w-to-access-firewall-nodes-without-vpn.rst |   0
 .../how-to-access-firewall-settings.rst       |   2 +-
 .../how-to-upgrade-firewall-os.rst            |   0
 .../sysadm}/network-architecture/idrac.rst    |   0
 .../sysadm}/network-architecture/index.rst    |   0
 .../reference-network-configuration.rst       |   0
 .../network-architecture/service-urls.rst     |   0
 .../puppet/howto-deploy-puppet-change.rst     |   0
 .../howto-manage-third-party-modules.rst      |   0
 .../puppet/howto-renew-agent-certificate.rst  |   0
 .../puppet/howto-test-changes-in-vagrant.rst  |   0
 {sysadm => docs/sysadm}/puppet/index.rst      |   0
 .../sysadm}/puppet/reference-architecture.rst |   0
 .../puppet/reference-best-practices.rst       |   0
 .../sysadm}/puppet/reference-setup.rst        |   0
 .../tutorial-my-first-change-in-puppet.rst    |   0
 .../backups/howto-access-backups.rst          |   0
 .../server-architecture/backups/index.rst     |   0
 .../backups/reference-infrastructure.rst      |   0
 .../howto-install-new-physical-server.rst     |   0
 .../howto-provision-new-vm.rst                |   0
 .../howto-search-inventory.rst                |   0
 .../howto-upgrade-machine.rst                 |   0
 .../sysadm}/server-architecture/index.rst     |   0
 .../reference-baseline-hardware.rst           |   0
 .../reference-inventory.rst                   |   0
 .../sysadm}/support-services/gitlab/index.rst |   0
 .../support-services/gitlab/installation.rst  |   0
 .../sysadm}/support-services/index.rst        |   0
 .../how-to-manage-creds-store.rst             |   0
 .../sysadm}/user-management/index.rst         |   0
 .../keycloak/authentication.rst               |   0
 .../keycloak/how-to-set-user-perms.rst        |   0
 .../user-management/keycloak/index.rst        |   0
 .../sysadm}/user-management/onboarding.rst    |   0
 .../sysadm}/user-management/openvpn/index.rst |   0
 .../user-management/openvpn/openvpn.rst       |   0
 .../openvpn/softwareheritage-ca-crt.rst       |   0
 .../sysadm}/user-management/outboarding.rst   |   0
 {user => docs/user}/.gitignore                |   0
 {user => docs/user}/Makefile                  |  18 +-
 {user => docs/user}/_static                   |   0
 {user => docs/user}/conf.py                   |   0
 {user => docs/user}/faq/index.rst             |   2 +-
 docs/user/index.rst                           |  22 ++
 {user => docs/user}/listers/arch.rst          |   0
 {user => docs/user}/listers/aur.rst           |   0
 {user => docs/user}/listers/bitbucket.rst     |   0
 {user => docs/user}/listers/bower.rst         |   0
 {user => docs/user}/listers/cgit.rst          |   0
 {user => docs/user}/listers/conda.rst         |   0
 {user => docs/user}/listers/cpan.rst          |   0
 {user => docs/user}/listers/cran.rst          |   0
 {user => docs/user}/listers/crates.rst        |   0
 {user => docs/user}/listers/debian.rst        |   0
 {user => docs/user}/listers/gitea.rst         |   0
 {user => docs/user}/listers/github.rst        |   0
 {user => docs/user}/listers/gitlab.rst        |   0
 {user => docs/user}/listers/gnu.rst           |   0
 {user => docs/user}/listers/gogs.rst          |   0
 {user => docs/user}/listers/golang.rst        |   0
 {user => docs/user}/listers/hackage.rst       |   0
 {user => docs/user}/listers/index.rst         |   0
 {user => docs/user}/listers/launchpad.rst     |   0
 {user => docs/user}/listers/maven.rst         |   0
 {user => docs/user}/listers/npm.rst           |   0
 {user => docs/user}/listers/opam.rst          |   0
 {user => docs/user}/listers/packagist.rst     |   0
 {user => docs/user}/listers/phabricator.rst   |   0
 {user => docs/user}/listers/pubdev.rst        |   0
 {user => docs/user}/listers/puppet.rst        |   0
 {user => docs/user}/listers/pypi.rst          |   0
 {user => docs/user}/listers/rubygems.rst      |   0
 {user => docs/user}/listers/sourceforge.rst   |   0
 {user => docs/user}/listers/tuleap.rst        |   0
 {user => docs/user}/loaders/arch.rst          |   0
 {user => docs/user}/loaders/archive.rst       |   0
 {user => docs/user}/loaders/aur.rst           |   0
 {user => docs/user}/loaders/bazaar.rst        |   0
 {user => docs/user}/loaders/conda.rst         |   0
 {user => docs/user}/loaders/cran.rst          |   0
 {user => docs/user}/loaders/crates.rst        |   0
 {user => docs/user}/loaders/cvs.rst           |   0
 {user => docs/user}/loaders/debian.rst        |   0
 {user => docs/user}/loaders/deposit.rst       |   0
 {user => docs/user}/loaders/git.rst           |   0
 {user => docs/user}/loaders/golang.rst        |   0
 {user => docs/user}/loaders/hackage.rst       |   0
 {user => docs/user}/loaders/index.rst         |   0
 {user => docs/user}/loaders/maven.rst         |   0
 {user => docs/user}/loaders/mercurial.rst     |   0
 {user => docs/user}/loaders/nixguix.rst       |   0
 {user => docs/user}/loaders/npm.rst           |   0
 {user => docs/user}/loaders/opam.rst          |   0
 {user => docs/user}/loaders/pubdev.rst        |   0
 {user => docs/user}/loaders/puppet.rst        |   0
 {user => docs/user}/loaders/pypi.rst          |   0
 {user => docs/user}/loaders/rubygems.rst      |   0
 {user => docs/user}/loaders/subversion.rst    |   0
 {user => docs/user}/logos/arch.png            | Bin
 {user => docs/user}/logos/archive.png         | Bin
 {user => docs/user}/logos/aur.png             | Bin
 {user => docs/user}/logos/bazaar.png          | Bin
 {user => docs/user}/logos/bitbucket.png       | Bin
 {user => docs/user}/logos/bower.png           | Bin
 {user => docs/user}/logos/cgit.png            | Bin
 {user => docs/user}/logos/conda.png           | Bin
 {user => docs/user}/logos/cpan.png            | Bin
 {user => docs/user}/logos/cran.png            | Bin
 {user => docs/user}/logos/crates.png          | Bin
 {user => docs/user}/logos/cvs.png             | Bin
 {user => docs/user}/logos/debian.png          | Bin
 {user => docs/user}/logos/deposit.png         | Bin
 {user => docs/user}/logos/git.png             | Bin
 {user => docs/user}/logos/gitea.png           | Bin
 {user => docs/user}/logos/github.png          | Bin
 {user => docs/user}/logos/gitlab.png          | Bin
 {user => docs/user}/logos/gnu.png             | Bin
 {user => docs/user}/logos/gogs.png            | Bin
 {user => docs/user}/logos/golang.png          | Bin
 {user => docs/user}/logos/hackage.png         | Bin
 {user => docs/user}/logos/launchpad.png       | Bin
 {user => docs/user}/logos/maven.png           | Bin
 {user => docs/user}/logos/mercurial.png       | Bin
 {user => docs/user}/logos/nixguix.png         | Bin
 {user => docs/user}/logos/npm.png             | Bin
 {user => docs/user}/logos/opam.png            | Bin
 {user => docs/user}/logos/packagist.png       | Bin
 {user => docs/user}/logos/phabricator.png     | Bin
 {user => docs/user}/logos/pubdev.png          | Bin
 {user => docs/user}/logos/puppet.png          | Bin
 {user => docs/user}/logos/pypi.png            | Bin
 {user => docs/user}/logos/rubygems.png        | Bin
 {user => docs/user}/logos/sourceforge.png     | Bin
 {user => docs/user}/logos/subversion.png      | Bin
 {user => docs/user}/logos/tuleap.png          | Bin
 {user => docs/user}/make.bat                  |   0
 .../user}/save_code_now/webhooks/index.rst    |   0
 requirements-swh-dev.txt                      |   1 +
 requirements-swh.txt                          |   1 +
 swh/docs/sphinx/conf.py                       |  31 +--
 sysadm/_templates/layout.html                 |  21 --
 tox.ini                                       |   5 +-
 266 files changed, 468 insertions(+), 420 deletions(-)
 delete mode 100755 docs/bin/ln-sphinx-subprojects
 create mode 100644 docs/devel/Makefile
 rename docs/{ => devel}/api-reference.rst (100%)
 rename docs/{ => devel}/architecture.rst (100%)
 rename docs/{ => devel}/architecture/index.rst (100%)
 rename docs/{ => devel}/architecture/metadata.rst (100%)
 rename docs/{ => devel}/architecture/overview.rst (100%)
 rename docs/{ => devel}/archive-changelog.rst (100%)
 rename docs/{ => devel}/bin/copy-and-fix-subprojects-indices (100%)
 create mode 100755 docs/devel/bin/ln-sphinx-subprojects
 rename docs/{ => devel}/bin/py-depgraph (100%)
 create mode 100644 docs/devel/conf.py
 rename docs/{ => devel}/contributing/code-review.rst (100%)
 rename docs/{ => devel}/contributing/git-style-guide.rst (100%)
 rename docs/{ => devel}/contributing/index.rst (100%)
 rename docs/{ => devel}/contributing/phabricator.rst (100%)
 rename docs/{ => devel}/contributing/python-style-guide.rst (100%)
 rename docs/{ => devel}/contributing/sphinx.rst (100%)
 rename docs/{ => devel}/contributing/tutorial-docs-contribution.rst (100%)
 rename docs/{ => devel}/developer-setup.rst (100%)
 rename docs/{ => devel}/faq/index.rst (100%)
 rename docs/{ => devel}/getting-started.rst (100%)
 rename docs/{ => devel}/getting-started/api.rst (100%)
 rename docs/{ => devel}/getting-started/index.rst (100%)
 create mode 100644 docs/devel/getting-started/using-docker.rst
 rename docs/{ => devel}/glossary.rst (100%)
 rename docs/{ => devel}/images/.gitignore (100%)
 rename docs/{ => devel}/images/Makefile (72%)
 rename docs/{ => devel}/images/architecture_diagram.dot (100%)
 rename docs/{ => devel}/images/elasticsearch.dot (100%)
 rename docs/{ => devel}/images/general-architecture.svg (100%)
 rename docs/{ => devel}/images/lister-loader-scheduling-architecture.svg (100%)
 rename docs/{ => devel}/images/tasks-git-loader.uml (100%)
 rename docs/{ => devel}/images/tasks-lister.uml (100%)
 create mode 100644 docs/devel/index.rst
 rename docs/{ => devel}/infrastructure.rst (100%)
 rename docs/{ => devel}/journal.rst (100%)
 rename docs/{ => devel}/keycloak.rst (100%)
 rename docs/{ => devel}/mirror.rst (100%)
 rename docs/{ => devel}/roadmap/index.rst (100%)
 rename docs/{ => devel}/roadmap/roadmap-2021.rst (100%)
 rename docs/{ => devel}/roadmap/roadmap-2022.rst (100%)
 rename docs/{ => devel}/services.txt (100%)
 rename docs/{ => devel}/statsd.rst (100%)
 rename docs/{ => devel}/swh-loader.rst (100%)
 rename docs/{ => devel}/tutorials/add-new-package.rst (100%)
 rename docs/{ => devel}/tutorials/index.rst (100%)
 rename docs/{ => devel}/tutorials/issue-debugging-monitoring.md (100%)
 rename docs/{ => devel}/tutorials/testing.rst (100%)
 delete mode 100644 docs/getting-started/using-docker.rst
 rename {sysadm => docs/sysadm}/.gitignore (100%)
 rename {sysadm => docs/sysadm}/Makefile (76%)
 rename {sysadm => docs/sysadm}/_static (100%)
 rename {sysadm => docs/sysadm}/conf.py (100%)
 rename {sysadm => docs/sysadm}/data-silos/cassandra/index.rst (100%)
 rename {sysadm => docs/sysadm}/data-silos/cassandra/installation.rst (100%)
 rename {sysadm => docs/sysadm}/data-silos/elasticsearch/index.rst (100%)
 rename {sysadm => docs/sysadm}/data-silos/index.rst (100%)
 rename {sysadm => docs/sysadm}/data-silos/kafka/index.rst (100%)
 rename {sysadm => docs/sysadm}/data-silos/kafka/manage-topics.rst (100%)
 rename {sysadm => docs/sysadm}/data-silos/postgresql/backup.rst (100%)
 rename {sysadm => docs/sysadm}/data-silos/postgresql/howto-connect.rst (100%)
 rename {sysadm => docs/sysadm}/data-silos/postgresql/index.rst (100%)
 rename {sysadm => docs/sysadm}/deployment/argocd.rst (100%)
 rename {sysadm => docs/sysadm}/deployment/deploy-lister.rst (100%)
 rename {sysadm => docs/sysadm}/deployment/deployment-environments.rst (100%)
 rename {sysadm => docs/sysadm}/deployment/howto-debian-packaging.rst (100%)
 rename {sysadm => docs/sysadm}/deployment/howto-process-add-forge-now-requests.rst (100%)
 rename {sysadm => docs/sysadm}/deployment/index.rst (100%)
 rename {sysadm => docs/sysadm}/deployment/jenkins.rst (100%)
 rename {sysadm => docs/sysadm}/deployment/storage-database-migration.rst (100%)
 rename {sysadm => docs/sysadm}/deployment/upgrade-swh-service.rst (100%)
 rename {sysadm => docs/sysadm}/getting-started/index.rst (100%)
 rename {sysadm => docs/sysadm}/getting-started/setup-repositories.rst (100%)
 rename {sysadm => docs/sysadm}/images/.gitignore (100%)
 rename {sysadm => docs/sysadm}/images/Makefile (100%)
 rename {sysadm => docs/sysadm}/images/gitlab-infrastructure.png (100%)
 rename {sysadm => docs/sysadm}/images/infrastructure/network/carp_maintenance.png (100%)
 rename {sysadm => docs/sysadm}/images/infrastructure/network/check_for_upgrade.png (100%)
 rename {sysadm => docs/sysadm}/images/infrastructure/network/proceed_update.png (100%)
 rename {sysadm => docs/sysadm}/images/infrastructure/network/reactivate_carp.png (100%)
 rename {sysadm => docs/sysadm}/images/infrastructure/network/sync.png (100%)
 rename {sysadm => docs/sysadm}/images/jenkins/300px-build-button.png (100%)
 rename {sysadm => docs/sysadm}/images/jenkins/300px-replay.png (100%)
 rename {sysadm => docs/sysadm}/images/jenkins/300px-restart-from-stage.png (100%)
 rename {sysadm => docs/sysadm}/images/jenkins/diff-report.png (100%)
 rename {sysadm => docs/sysadm}/images/jenkins/revision-report.png (100%)
 rename {sysadm => docs/sysadm}/images/keycloak_add_user_01.jpg (100%)
 rename {sysadm => docs/sysadm}/images/keycloak_add_user_02.jpg (100%)
 rename {sysadm => docs/sysadm}/images/keycloak_add_user_03.jpg (100%)
 rename {sysadm => docs/sysadm}/images/keycloak_add_user_permission_01.jpg (100%)
 rename {sysadm => docs/sysadm}/images/keycloak_add_user_permission_02.jpg (100%)
 rename {sysadm => docs/sysadm}/images/keycloak_add_user_permission_03.jpg (100%)
 rename {sysadm => docs/sysadm}/images/keycloak_add_user_permission_04.jpg (100%)
 rename {sysadm => docs/sysadm}/images/mirror-architecture.svg (100%)
 rename {sysadm => docs/sysadm}/images/network.uml (100%)
 rename {sysadm => docs/sysadm}/images/openvpn/nm-openvpn-advanced-general.png (100%)
 rename {sysadm => docs/sysadm}/images/openvpn/nm-openvpn-advanced-security.png (100%)
 rename {sysadm => docs/sysadm}/images/openvpn/nm-openvpn-advanced-tls-auth.png (100%)
 rename {sysadm => docs/sysadm}/images/openvpn/nm-openvpn-base.png (100%)
 rename {sysadm => docs/sysadm}/images/openvpn/nm-openvpn-routes.png (100%)
 rename {sysadm => docs/sysadm}/images/openvpn/vpn-csr-certificate.png (100%)
 rename {sysadm => docs/sysadm}/images/openvpn/vpn-csr-signing.png (100%)
 rename {sysadm => docs/sysadm}/images/openvpn/vpn-ctrl-list.png (100%)
 rename {sysadm => docs/sysadm}/images/openvpn/vpn-main-trust-page.png (100%)
 rename {sysadm => docs/sysadm}/images/staging-environment.uml (100%)
 rename {sysadm => docs/sysadm}/index.rst (58%)
 rename {sysadm => docs/sysadm}/life-cycle-management/how-to-manage-tools-upgrades.rst (98%)
 rename {sysadm => docs/sysadm}/life-cycle-management/how-to-new-service-backup.rst (100%)
 rename {sysadm => docs/sysadm}/life-cycle-management/index.rst (100%)
 rename {sysadm => docs/sysadm}/make.bat (100%)
 rename {sysadm => docs/sysadm}/mirror-operations/deploy.rst (100%)
 rename {sysadm => docs/sysadm}/mirror-operations/docker.rst (99%)
 rename {sysadm => docs/sysadm}/mirror-operations/index.rst (100%)
 rename {sysadm => docs/sysadm}/mirror-operations/monitor.rst (100%)
 rename {sysadm => docs/sysadm}/mirror-operations/onboard.rst (100%)
 rename {sysadm => docs/sysadm}/mirror-operations/planning.rst (100%)
 rename {sysadm => docs/sysadm}/network-architecture/dns.rst (100%)
 rename {sysadm => docs/sysadm}/network-architecture/how-to-access-firewall-nodes-without-vpn.rst (100%)
 rename {sysadm => docs/sysadm}/network-architecture/how-to-access-firewall-settings.rst (98%)
 rename {sysadm => docs/sysadm}/network-architecture/how-to-upgrade-firewall-os.rst (100%)
 rename {sysadm => docs/sysadm}/network-architecture/idrac.rst (100%)
 rename {sysadm => docs/sysadm}/network-architecture/index.rst (100%)
 rename {sysadm => docs/sysadm}/network-architecture/reference-network-configuration.rst (100%)
 rename {sysadm => docs/sysadm}/network-architecture/service-urls.rst (100%)
 rename {sysadm => docs/sysadm}/puppet/howto-deploy-puppet-change.rst (100%)
 rename {sysadm => docs/sysadm}/puppet/howto-manage-third-party-modules.rst (100%)
 rename {sysadm => docs/sysadm}/puppet/howto-renew-agent-certificate.rst (100%)
 rename {sysadm => docs/sysadm}/puppet/howto-test-changes-in-vagrant.rst (100%)
 rename {sysadm => docs/sysadm}/puppet/index.rst (100%)
 rename {sysadm => docs/sysadm}/puppet/reference-architecture.rst (100%)
 rename {sysadm => docs/sysadm}/puppet/reference-best-practices.rst (100%)
 rename {sysadm => docs/sysadm}/puppet/reference-setup.rst (100%)
 rename {sysadm => docs/sysadm}/puppet/tutorial-my-first-change-in-puppet.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/backups/howto-access-backups.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/backups/index.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/backups/reference-infrastructure.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/howto-install-new-physical-server.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/howto-provision-new-vm.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/howto-search-inventory.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/howto-upgrade-machine.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/index.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/reference-baseline-hardware.rst (100%)
 rename {sysadm => docs/sysadm}/server-architecture/reference-inventory.rst (100%)
 rename {sysadm => docs/sysadm}/support-services/gitlab/index.rst (100%)
 rename {sysadm => docs/sysadm}/support-services/gitlab/installation.rst (100%)
 rename {sysadm => docs/sysadm}/support-services/index.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/how-to-manage-creds-store.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/index.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/keycloak/authentication.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/keycloak/how-to-set-user-perms.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/keycloak/index.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/onboarding.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/openvpn/index.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/openvpn/openvpn.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/openvpn/softwareheritage-ca-crt.rst (100%)
 rename {sysadm => docs/sysadm}/user-management/outboarding.rst (100%)
 rename {user => docs/user}/.gitignore (100%)
 rename {user => docs/user}/Makefile (58%)
 rename {user => docs/user}/_static (100%)
 rename {user => docs/user}/conf.py (100%)
 rename {user => docs/user}/faq/index.rst (99%)
 create mode 100644 docs/user/index.rst
 rename {user => docs/user}/listers/arch.rst (100%)
 rename {user => docs/user}/listers/aur.rst (100%)
 rename {user => docs/user}/listers/bitbucket.rst (100%)
 rename {user => docs/user}/listers/bower.rst (100%)
 rename {user => docs/user}/listers/cgit.rst (100%)
 rename {user => docs/user}/listers/conda.rst (100%)
 rename {user => docs/user}/listers/cpan.rst (100%)
 rename {user => docs/user}/listers/cran.rst (100%)
 rename {user => docs/user}/listers/crates.rst (100%)
 rename {user => docs/user}/listers/debian.rst (100%)
 rename {user => docs/user}/listers/gitea.rst (100%)
 rename {user => docs/user}/listers/github.rst (100%)
 rename {user => docs/user}/listers/gitlab.rst (100%)
 rename {user => docs/user}/listers/gnu.rst (100%)
 rename {user => docs/user}/listers/gogs.rst (100%)
 rename {user => docs/user}/listers/golang.rst (100%)
 rename {user => docs/user}/listers/hackage.rst (100%)
 rename {user => docs/user}/listers/index.rst (100%)
 rename {user => docs/user}/listers/launchpad.rst (100%)
 rename {user => docs/user}/listers/maven.rst (100%)
 rename {user => docs/user}/listers/npm.rst (100%)
 rename {user => docs/user}/listers/opam.rst (100%)
 rename {user => docs/user}/listers/packagist.rst (100%)
 rename {user => docs/user}/listers/phabricator.rst (100%)
 rename {user => docs/user}/listers/pubdev.rst (100%)
 rename {user => docs/user}/listers/puppet.rst (100%)
 rename {user => docs/user}/listers/pypi.rst (100%)
 rename {user => docs/user}/listers/rubygems.rst (100%)
 rename {user => docs/user}/listers/sourceforge.rst (100%)
 rename {user => docs/user}/listers/tuleap.rst (100%)
 rename {user => docs/user}/loaders/arch.rst (100%)
 rename {user => docs/user}/loaders/archive.rst (100%)
 rename {user => docs/user}/loaders/aur.rst (100%)
 rename {user => docs/user}/loaders/bazaar.rst (100%)
 rename {user => docs/user}/loaders/conda.rst (100%)
 rename {user => docs/user}/loaders/cran.rst (100%)
 rename {user => docs/user}/loaders/crates.rst (100%)
 rename {user => docs/user}/loaders/cvs.rst (100%)
 rename {user => docs/user}/loaders/debian.rst (100%)
 rename {user => docs/user}/loaders/deposit.rst (100%)
 rename {user => docs/user}/loaders/git.rst (100%)
 rename {user => docs/user}/loaders/golang.rst (100%)
 rename {user => docs/user}/loaders/hackage.rst (100%)
 rename {user => docs/user}/loaders/index.rst (100%)
 rename {user => docs/user}/loaders/maven.rst (100%)
 rename {user => docs/user}/loaders/mercurial.rst (100%)
 rename {user => docs/user}/loaders/nixguix.rst (100%)
 rename {user => docs/user}/loaders/npm.rst (100%)
 rename {user => docs/user}/loaders/opam.rst (100%)
 rename {user => docs/user}/loaders/pubdev.rst (100%)
 rename {user => docs/user}/loaders/puppet.rst (100%)
 rename {user => docs/user}/loaders/pypi.rst (100%)
 rename {user => docs/user}/loaders/rubygems.rst (100%)
 rename {user => docs/user}/loaders/subversion.rst (100%)
 rename {user => docs/user}/logos/arch.png (100%)
 rename {user => docs/user}/logos/archive.png (100%)
 rename {user => docs/user}/logos/aur.png (100%)
 rename {user => docs/user}/logos/bazaar.png (100%)
 rename {user => docs/user}/logos/bitbucket.png (100%)
 rename {user => docs/user}/logos/bower.png (100%)
 rename {user => docs/user}/logos/cgit.png (100%)
 rename {user => docs/user}/logos/conda.png (100%)
 rename {user => docs/user}/logos/cpan.png (100%)
 rename {user => docs/user}/logos/cran.png (100%)
 rename {user => docs/user}/logos/crates.png (100%)
 rename {user => docs/user}/logos/cvs.png (100%)
 rename {user => docs/user}/logos/debian.png (100%)
 rename {user => docs/user}/logos/deposit.png (100%)
 rename {user => docs/user}/logos/git.png (100%)
 rename {user => docs/user}/logos/gitea.png (100%)
 rename {user => docs/user}/logos/github.png (100%)
 rename {user => docs/user}/logos/gitlab.png (100%)
 rename {user => docs/user}/logos/gnu.png (100%)
 rename {user => docs/user}/logos/gogs.png (100%)
 rename {user => docs/user}/logos/golang.png (100%)
 rename {user => docs/user}/logos/hackage.png (100%)
 rename {user => docs/user}/logos/launchpad.png (100%)
 rename {user => docs/user}/logos/maven.png (100%)
 rename {user => docs/user}/logos/mercurial.png (100%)
 rename {user => docs/user}/logos/nixguix.png (100%)
 rename {user => docs/user}/logos/npm.png (100%)
 rename {user => docs/user}/logos/opam.png (100%)
 rename {user => docs/user}/logos/packagist.png (100%)
 rename {user => docs/user}/logos/phabricator.png (100%)
 rename {user => docs/user}/logos/pubdev.png (100%)
 rename {user => docs/user}/logos/puppet.png (100%)
 rename {user => docs/user}/logos/pypi.png (100%)
 rename {user => docs/user}/logos/rubygems.png (100%)
 rename {user => docs/user}/logos/sourceforge.png (100%)
 rename {user => docs/user}/logos/subversion.png (100%)
 rename {user => docs/user}/logos/tuleap.png (100%)
 rename {user => docs/user}/make.bat (100%)
 rename {user => docs/user}/save_code_now/webhooks/index.rst (100%)
 delete mode 100644 sysadm/_templates/layout.html

diff --git a/Makefile.local b/Makefile.local
index f9e0cd0f..37c74179 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -7,6 +7,8 @@ all:
 	@echo Please be patient.
 	tox -vv -r -e sphinx-dev
 
+clean:
+	make -C docs clean
 
 # inline *build* dependencies to allow installing requirements-swh-dev.txt without build
 # isolation
diff --git a/docs/.gitignore b/docs/.gitignore
index 1fb132de..25643c45 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,5 +1,5 @@
 *-stamp
 _build/
-/swh-*
+devel/swh-*
 !/swh-loader.rst
 sources/
diff --git a/docs/Makefile b/docs/Makefile
index aa4a0f81..f0345534 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,74 +1,44 @@
-SPHINXOPTS ?=
-SPHINXOPTCOLOR ?= --color
-SPHINXBUILD = sphinx-build
-SOURCEDIR = .
-BUILDDIR = _build
-HTMLDIR = $(BUILDDIR)/html
-SWHPKGDIR ?= sources/swh/
-
-INSTALL_HOST = pergamon.internal.softwareheritage.org
-INSTALL_DIR = /srv/softwareheritage/docs/webroot/devel
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS  ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR    = .
+BUILDDIR     = _build
+HTMLDIR      = $(BUILDDIR)/html
+
+INSTALL_HOST  = pergamon.internal.softwareheritage.org
+INSTALL_DIR   = /srv/softwareheritage/docs/webroot
 INSTALL_GROUP = swhdev
 INSTALL_PERMS = g+rwX
 
-SPHINXAPIDOC = sphinx-apidoc
-APIDOC_DIR = apidoc
-APIDOC_OPTS = --ext-viewcode --separate --no-toc
-APIDOC_EXCLUDES = */tests */migrations */wsgi.py */conftest.py */setup.py
-APIDOC_EXCLUDES += deposit/settings/* web/settings/* dataset/*
-APIDOC_SWH_EXCLUDES = $(patsubst %,"$(SWHPKGDIR)/%",$(APIDOC_EXCLUDES))
+.PHONY: help images apidoc html clean install
 
-html: sphinx/html
+all: html
 
-sphinx/html: links-stamp apidoc-stamp images-stamp rec-build-stamp
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+sphinx/%: Makefile images apidoc
+	@$(SPHINXBUILD) -M $* "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-links-stamp:
-	mkdir -p sources/swh
-	bin/ln-sphinx-subprojects
-	touch $@
+sphinx/clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-apidoc: apidoc-stamp
-apidoc-stamp: links-stamp
-	$(SPHINXAPIDOC) \
-		--implicit-namespaces \
-		--templatedir=../swh/docs/templates/ \
-		--maxdepth=3 \
-		$(APIDOC_OPTS) \
-		-o $(APIDOC_DIR) \
-		$(SWHPKGDIR) \
-		$(APIDOC_SWH_EXCLUDES)
-	touch $@
-	# remove warning about swh.rst not being included in any toctree
-	sed -i '1s/^/:orphan:\n\n/' $(APIDOC_DIR)/swh.rst
+images:
+	$(MAKE) -C devel images-stamp
+	$(MAKE) -C sysadm images-stamp
 
-images-stamp:
-	$(MAKE) -C images
-	$(MAKE) -C swh-deposit/images
-	touch $@
+apidoc:
+	$(MAKE) -C devel apidoc
 
-# Build documentation recursively in all packages, to make sure that auxiliary,
-# non-sphinx managed documentation artifacts (e.g., schema diagrams) are also
-# built.
-rec-build-stamp: $(wildcard ../../swh-*/docs/*.rst)
-	$(MAKE) -C ../../ docs-assets
-	touch $@
+html: sphinx/html
 
 clean: sphinx/clean
-	bin/ln-sphinx-subprojects --remove
-	$(MAKE) -C images clean
-	rm -f *-stamp
-	rm -f $(APIDOC_DIR)/*
-
-distclean: clean
-	make -C ../../ docs-clean
-
-help: sphinx/help
-
-sphinx/clean:
-	$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(SPHINXOPTCOLOR)
-
-sphinx/%:
-	$(SPHINXBUILD) -b $* "$(SOURCEDIR)" "$(BUILDDIR)/$*" $(SPHINXOPTS) $(SPHINXOPTCOLOR)
+	$(MAKE) -C devel clean
+	$(MAKE) -C sysadm clean
+	$(MAKE) -C user clean
 
 install: html
 	test -d $(HTMLDIR)
@@ -77,5 +47,3 @@ install: html
 		"find $(INSTALL_DIR) -not -group $(INSTALL_GROUP) -exec chgrp -v $(INSTALL_GROUP) {} + ; \
 		 find $(INSTALL_DIR) -not -perm -ug=rw,o=r -exec chmod -v ug+rw,o+r {} + ; \
 		 find $(INSTALL_DIR) -type d -not -perm -g=xs,ou=x -exec chmod -v g+xs,ou+x {} +"
-
-.PHONY: help html clean distclean install images-stamp
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
index e91b38fb..6d87fe82 100644
--- a/docs/_templates/layout.html
+++ b/docs/_templates/layout.html
@@ -15,24 +15,3 @@
 </script>
 <!-- End Matomo Code -->
 {% endblock %}
-
-
-{# copied from sphinx_rtd_theme/layout.html, with the extra System Administration link #}
-{%- block menu %}
-  {%- set toctree = toctree(maxdepth=theme_navigation_depth|int,
-                            collapse=theme_collapse_navigation|tobool,
-                            includehidden=theme_includehidden|tobool,
-                            titles_only=theme_titles_only|tobool) %}
-  {%- if toctree %}
-    {{ toctree }}
-  {%- else %}
-    <!-- Local TOC -->
-    <div class="local-toc">{{ toc }}</div>
-  {%- endif %}
-
-  <hr />
-
-  <ul>
-      <li class="toctree-l1"><a href="/sysadm/">System Administration</a></li>
-  </ul>
-{%- endblock %}
diff --git a/docs/bin/ln-sphinx-subprojects b/docs/bin/ln-sphinx-subprojects
deleted file mode 100755
index 9d6e439c..00000000
--- a/docs/bin/ln-sphinx-subprojects
+++ /dev/null
@@ -1,35 +0,0 @@
-#!/bin/bash
-set -e
-
-create_links () {
-    mkdir -p sources
-    for pymodule in $(cd ../../ && bin/ls-py-modules) ; do
-        if [ "$pymodule" = 'swh-docs' ] ; then
-            continue
-        fi
-        if [ ! -e "$pymodule" -a -d "../../${pymodule}/docs" ] ; then
-            ln -s "../../${pymodule}/docs" "$pymodule"
-        fi
-        if [ -d "../../${pymodule}/swh" ] ; then
-            cp -r -f --symbolic-link $(realpath ../../${pymodule}/swh/*) sources/swh/
-        fi
-    done
-}
-
-remove_links () {
-    for pymodule in $(cd ../../ && bin/ls-py-modules) ; do
-        if [ "$pymodule" = 'swh-docs' ] ; then
-            continue
-        fi
-        if [ -L "$pymodule" ] ; then
-            rm "$pymodule"
-        fi
-    done
-    rm -rf sources/swh/
-}
-
-if [ "$1" = "--remove" ] ; then
-    remove_links
-else
-    create_links
-fi
diff --git a/docs/devel/Makefile b/docs/devel/Makefile
new file mode 100644
index 00000000..761f2787
--- /dev/null
+++ b/docs/devel/Makefile
@@ -0,0 +1,66 @@
+SPHINXOPTS ?= -t devel_doc
+SPHINXOPTCOLOR ?= --color
+SPHINXBUILD = sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+SWHPKGDIR ?= sources/swh/
+
+SPHINXAPIDOC = sphinx-apidoc
+APIDOC_DIR = apidoc
+APIDOC_OPTS = --ext-viewcode --separate --no-toc
+APIDOC_EXCLUDES = */tests */migrations */wsgi.py */conftest.py */setup.py
+APIDOC_EXCLUDES += deposit/settings/* web/settings/* dataset/*
+APIDOC_SWH_EXCLUDES = $(patsubst %,"$(SWHPKGDIR)/%",$(APIDOC_EXCLUDES))
+
+all: html
+
+html: sphinx/html
+
+sphinx/html: links-stamp apidoc-stamp images-stamp rec-build-stamp
+
+links-stamp:
+	mkdir -p sources/swh
+	bin/ln-sphinx-subprojects
+	touch $@
+
+apidoc: apidoc-stamp
+apidoc-stamp: links-stamp
+	$(SPHINXAPIDOC) \
+		--implicit-namespaces \
+		--templatedir=../../swh/docs/templates/ \
+		--maxdepth=3 \
+		$(APIDOC_OPTS) \
+		-o $(APIDOC_DIR) \
+		$(SWHPKGDIR) \
+		$(APIDOC_SWH_EXCLUDES)
+	touch $@
+	# remove warning about swh.rst not being included in any toctree
+	sed -i '1s/^/:orphan:\n\n/' $(APIDOC_DIR)/swh.rst
+
+images-stamp:
+	$(MAKE) -C images
+	touch $@
+
+# Build documentation recursively in all packages, to make sure that auxiliary,
+# non-sphinx managed documentation artifacts (e.g., schema diagrams) are also
+# built.
+rec-build-stamp: $(wildcard ../../swh-*/docs/*.rst)
+	$(MAKE) -C ../../../ docs-assets
+	touch $@
+
+clean: sphinx/clean
+	bin/ln-sphinx-subprojects --remove
+	$(MAKE) -C images clean
+	rm -f *-stamp
+	rm -f $(APIDOC_DIR)/*
+
+distclean: clean
+	make -C ../../../ docs-clean
+
+sphinx/clean:
+	$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(SPHINXOPTCOLOR)
+
+sphinx/%:
+	$(SPHINXBUILD) -b $* "$(SOURCEDIR)" "$(BUILDDIR)/$*" $(SPHINXOPTS) $(SPHINXOPTCOLOR)
+
+.PHONY: html clean distclean install
diff --git a/docs/api-reference.rst b/docs/devel/api-reference.rst
similarity index 100%
rename from docs/api-reference.rst
rename to docs/devel/api-reference.rst
diff --git a/docs/architecture.rst b/docs/devel/architecture.rst
similarity index 100%
rename from docs/architecture.rst
rename to docs/devel/architecture.rst
diff --git a/docs/architecture/index.rst b/docs/devel/architecture/index.rst
similarity index 100%
rename from docs/architecture/index.rst
rename to docs/devel/architecture/index.rst
diff --git a/docs/architecture/metadata.rst b/docs/devel/architecture/metadata.rst
similarity index 100%
rename from docs/architecture/metadata.rst
rename to docs/devel/architecture/metadata.rst
diff --git a/docs/architecture/overview.rst b/docs/devel/architecture/overview.rst
similarity index 100%
rename from docs/architecture/overview.rst
rename to docs/devel/architecture/overview.rst
diff --git a/docs/archive-changelog.rst b/docs/devel/archive-changelog.rst
similarity index 100%
rename from docs/archive-changelog.rst
rename to docs/devel/archive-changelog.rst
diff --git a/docs/bin/copy-and-fix-subprojects-indices b/docs/devel/bin/copy-and-fix-subprojects-indices
similarity index 100%
rename from docs/bin/copy-and-fix-subprojects-indices
rename to docs/devel/bin/copy-and-fix-subprojects-indices
diff --git a/docs/devel/bin/ln-sphinx-subprojects b/docs/devel/bin/ln-sphinx-subprojects
new file mode 100755
index 00000000..edd5d6f3
--- /dev/null
+++ b/docs/devel/bin/ln-sphinx-subprojects
@@ -0,0 +1,39 @@
+#!/bin/bash
+set -e
+
+create_links () {
+    mkdir -p sources
+    for pymodule in $(cd ../../../ && bin/ls-py-modules) ; do
+        if [ "$pymodule" = 'swh-docs' ] ; then
+            continue
+        fi
+        if [ ! -e "$pymodule" -a -d "../../../${pymodule}/docs" ] ; then
+            ln -s "../../../${pymodule}/docs" "$pymodule"
+        fi
+        if [ -f "$pymodule/images/Makefile" ] ; then
+            make -C $pymodule images
+        fi
+        if [ -d "../../../${pymodule}/swh" ] ; then
+            cp -r -f --symbolic-link $(realpath ../../../${pymodule}/swh/*) sources/swh/
+        fi
+    done
+}
+
+remove_links () {
+    for pymodule in $(cd ../../../ && bin/ls-py-modules) ; do
+        if [ "$pymodule" = 'swh-docs' ] ; then
+            continue
+        fi
+        if [ -L "$pymodule" ] ; then
+            make -C $pymodule clean
+            rm "$pymodule"
+        fi
+    done
+    rm -rf sources/swh/
+}
+
+if [ "$1" = "--remove" ] ; then
+    remove_links
+else
+    create_links
+fi
diff --git a/docs/bin/py-depgraph b/docs/devel/bin/py-depgraph
similarity index 100%
rename from docs/bin/py-depgraph
rename to docs/devel/bin/py-depgraph
diff --git a/docs/devel/conf.py b/docs/devel/conf.py
new file mode 100644
index 00000000..675e63f8
--- /dev/null
+++ b/docs/devel/conf.py
@@ -0,0 +1 @@
+from swh.docs.sphinx.conf import *  # noqa
diff --git a/docs/contributing/code-review.rst b/docs/devel/contributing/code-review.rst
similarity index 100%
rename from docs/contributing/code-review.rst
rename to docs/devel/contributing/code-review.rst
diff --git a/docs/contributing/git-style-guide.rst b/docs/devel/contributing/git-style-guide.rst
similarity index 100%
rename from docs/contributing/git-style-guide.rst
rename to docs/devel/contributing/git-style-guide.rst
diff --git a/docs/contributing/index.rst b/docs/devel/contributing/index.rst
similarity index 100%
rename from docs/contributing/index.rst
rename to docs/devel/contributing/index.rst
diff --git a/docs/contributing/phabricator.rst b/docs/devel/contributing/phabricator.rst
similarity index 100%
rename from docs/contributing/phabricator.rst
rename to docs/devel/contributing/phabricator.rst
diff --git a/docs/contributing/python-style-guide.rst b/docs/devel/contributing/python-style-guide.rst
similarity index 100%
rename from docs/contributing/python-style-guide.rst
rename to docs/devel/contributing/python-style-guide.rst
diff --git a/docs/contributing/sphinx.rst b/docs/devel/contributing/sphinx.rst
similarity index 100%
rename from docs/contributing/sphinx.rst
rename to docs/devel/contributing/sphinx.rst
diff --git a/docs/contributing/tutorial-docs-contribution.rst b/docs/devel/contributing/tutorial-docs-contribution.rst
similarity index 100%
rename from docs/contributing/tutorial-docs-contribution.rst
rename to docs/devel/contributing/tutorial-docs-contribution.rst
diff --git a/docs/developer-setup.rst b/docs/devel/developer-setup.rst
similarity index 100%
rename from docs/developer-setup.rst
rename to docs/devel/developer-setup.rst
diff --git a/docs/faq/index.rst b/docs/devel/faq/index.rst
similarity index 100%
rename from docs/faq/index.rst
rename to docs/devel/faq/index.rst
diff --git a/docs/getting-started.rst b/docs/devel/getting-started.rst
similarity index 100%
rename from docs/getting-started.rst
rename to docs/devel/getting-started.rst
diff --git a/docs/getting-started/api.rst b/docs/devel/getting-started/api.rst
similarity index 100%
rename from docs/getting-started/api.rst
rename to docs/devel/getting-started/api.rst
diff --git a/docs/getting-started/index.rst b/docs/devel/getting-started/index.rst
similarity index 100%
rename from docs/getting-started/index.rst
rename to docs/devel/getting-started/index.rst
diff --git a/docs/devel/getting-started/using-docker.rst b/docs/devel/getting-started/using-docker.rst
new file mode 100644
index 00000000..9656ebe7
--- /dev/null
+++ b/docs/devel/getting-started/using-docker.rst
@@ -0,0 +1,3 @@
+.. _docker-environment:
+
+.. include:: ../../../../docker/README.rst
diff --git a/docs/glossary.rst b/docs/devel/glossary.rst
similarity index 100%
rename from docs/glossary.rst
rename to docs/devel/glossary.rst
diff --git a/docs/images/.gitignore b/docs/devel/images/.gitignore
similarity index 100%
rename from docs/images/.gitignore
rename to docs/devel/images/.gitignore
diff --git a/docs/images/Makefile b/docs/devel/images/Makefile
similarity index 72%
rename from docs/images/Makefile
rename to docs/devel/images/Makefile
index 9a83a34a..abfc3bea 100644
--- a/docs/images/Makefile
+++ b/docs/devel/images/Makefile
@@ -1,5 +1,5 @@
 
-PY_REQUIREMENTS = $(wildcard ../../../*/requirements*.txt)
+PY_REQUIREMENTS = $(wildcard ../../../../*/requirements*.txt)
 DEP_GRAPHS_base = py-deps-all py-deps-swh py-deps-ext
 DEP_GRAPHS += $(patsubst %,%.dot,$(DEP_GRAPHS_base))
 DEP_GRAPHS += $(patsubst %,%.pdf,$(DEP_GRAPHS_base))
@@ -12,13 +12,13 @@ UML_DIAGS = $(patsubst %.uml,%.svg,$(UML_DIAGS_SRC))
 all: $(DEP_GRAPHS) $(UML_DIAGS)
 
 py-deps-all.dot: $(PY_DEPGRAPH) $(PY_REQUIREMENTS)
-	cd ../../.. ; $(CURDIR)/$(PY_DEPGRAPH) > $(CURDIR)/$@
+	cd ../../../.. ; $(CURDIR)/$(PY_DEPGRAPH) > $(CURDIR)/$@
 
 py-deps-swh.dot: $(PY_DEPGRAPH) $(PY_REQUIREMENTS)
-	cd ../../.. ; $(CURDIR)/$(PY_DEPGRAPH) --no-external > $(CURDIR)/$@
+	cd ../../../.. ; $(CURDIR)/$(PY_DEPGRAPH) --no-external > $(CURDIR)/$@
 
 py-deps-ext.dot: $(PY_DEPGRAPH) $(PY_REQUIREMENTS)
-	cd ../../.. ; $(CURDIR)/$(PY_DEPGRAPH) --no-internal > $(CURDIR)/$@
+	cd ../../../.. ; $(CURDIR)/$(PY_DEPGRAPH) --no-internal > $(CURDIR)/$@
 
 %.pdf: %.dot
 	dot -T pdf $< > $@
diff --git a/docs/images/architecture_diagram.dot b/docs/devel/images/architecture_diagram.dot
similarity index 100%
rename from docs/images/architecture_diagram.dot
rename to docs/devel/images/architecture_diagram.dot
diff --git a/docs/images/elasticsearch.dot b/docs/devel/images/elasticsearch.dot
similarity index 100%
rename from docs/images/elasticsearch.dot
rename to docs/devel/images/elasticsearch.dot
diff --git a/docs/images/general-architecture.svg b/docs/devel/images/general-architecture.svg
similarity index 100%
rename from docs/images/general-architecture.svg
rename to docs/devel/images/general-architecture.svg
diff --git a/docs/images/lister-loader-scheduling-architecture.svg b/docs/devel/images/lister-loader-scheduling-architecture.svg
similarity index 100%
rename from docs/images/lister-loader-scheduling-architecture.svg
rename to docs/devel/images/lister-loader-scheduling-architecture.svg
diff --git a/docs/images/tasks-git-loader.uml b/docs/devel/images/tasks-git-loader.uml
similarity index 100%
rename from docs/images/tasks-git-loader.uml
rename to docs/devel/images/tasks-git-loader.uml
diff --git a/docs/images/tasks-lister.uml b/docs/devel/images/tasks-lister.uml
similarity index 100%
rename from docs/images/tasks-lister.uml
rename to docs/devel/images/tasks-lister.uml
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
new file mode 100644
index 00000000..daaedaf1
--- /dev/null
+++ b/docs/devel/index.rst
@@ -0,0 +1,243 @@
+.. _swh-docs-devel:
+
+Software Heritage - Development Documentation
+=============================================
+
+Important documentation links
+-----------------------------
+
+Getting started
+^^^^^^^^^^^^^^^
+
+* :ref:`getting-started` → deploy a local copy of the Software Heritage
+  software stack in less than 5 minutes, or
+* :ref:`developer-setup` → get a working development setup that allows to hack
+  on the Software Heritage software stack
+* :ref:`faq`
+
+Contributing
+^^^^^^^^^^^^
+
+* :ref:`patch-submission` → learn how to submit your patches to the
+  Software Heritage codebase
+* :ref:`code-review` → rules and guidelines to review code in
+  Software Heritage
+* :ref:`python-style-guide` → how to format the Python code you write
+
+Architecture
+^^^^^^^^^^^^
+
+* :ref:`architecture-overview` → get a glimpse of the Software Heritage software
+  architecture
+* :ref:`Metadata workflow <architecture-metadata>` → learn how Software Heritage
+  stores and handles metadata
+
+Data Model and Specifications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* :ref:`persistent-identifiers` Specifications of the SoftWare Heritage persistent IDentifiers (SWHID).
+* :ref:`data-model` Documentation of the main |swh| archive data model.
+* :ref:`journal-specs` Documentation of the Kafka journal of the |swh| archive.
+
+Tutorials
+^^^^^^^^^
+
+* :ref:`testing-guide`
+* :doc:`tutorials/issue-debugging-monitoring`
+* :ref:`Listing the content of your favorite forge <lister-tutorial>`
+  and :ref:`running a lister in Docker <run-lister-tutorial>`
+* :ref:`Add a new swh package <tutorial-new-package>`
+* :ref:`doc-contribution`
+
+Roadmap
+^^^^^^^
+
+* Current roadmap: :ref:`roadmap-current`
+* Previous roadmaps
+
+  * :ref:`roadmap-2021`
+
+System Administration
+^^^^^^^^^^^^^^^^^^^^^
+
+* :ref:`Network Infrastructure <swh-sysadm:infrastructure>`
+* :ref:`swh-sysadm:mirror` → learn what a Software Heritage mirror is and how to set up
+  one
+* :ref:`Keycloak <swh-sysadm:keycloak>` → learn how to use Keycloak,
+  the authentication system used by |swh|'s web interface and public APIs
+
+.. _components:
+
+Components
+^^^^^^^^^^
+
+Here is brief overview of the most relevant software components in the Software
+Heritage stack, in alphabetical order.
+For a better introduction to the architecture, see the :ref:`architecture-overview`,
+which presents each of them in a didactical order.
+
+Each component name is linked to the development documentation
+of the corresponding Python module.
+
+:ref:`swh.auth <swh-auth>`
+    low-level library used by modules needing keycloak authentication
+
+:ref:`swh.core <swh-core>`
+    low-level utilities and helpers used by almost all other modules in the
+    stack
+
+:ref:`swh.counters <swh-counters>`
+    service providing efficient estimates of the number of objects in the SWH archive,
+    using Redis's Hyperloglog
+
+:ref:`swh.dataset <swh-dataset>`
+    public datasets and periodic data dumps of the archive released by Software
+    Heritage
+
+:ref:`swh.deposit <swh-deposit>`
+    push-based deposit of software artifacts to the archive
+
+swh.docs
+    developer documentation (used to generate this doc you are reading)
+
+:ref:`swh.fuse <swh-fuse>`
+    Virtual file system to browse the Software Heritage archive, based on
+    `FUSE <https://github.com/libfuse/libfuse>`_
+
+:ref:`swh.graph <swh-graph>`
+    Fast, compressed, in-memory representation of the archive, with tooling to
+    generate and query it.
+
+:ref:`swh.graphql <swh-graphql>`
+    GraphQL API to request archive data offering more precise and flexible queries
+    than the REST API.
+
+:ref:`swh.indexer <swh-indexer>`
+    tools and workers used to crawl the content of the archive and extract
+    derived information from any artifact stored in it
+
+:ref:`swh.journal <swh-journal>`
+    persistent logger of changes to the archive, with publish-subscribe support
+
+:ref:`swh.lister <swh-lister>`
+    collection of listers for all sorts of source code hosting and distribution
+    places (forges, distributions, package managers, etc.)
+
+:ref:`swh.loader-core <swh-loader-core>`
+    low-level loading utilities and helpers used by all other loaders
+
+:ref:`swh.loader-bzr <swh-loader-bzr>`
+    loader for `Bazaar <http://bazaar.canonical.com/en/>`_ and
+    `Breezy <https://www.breezy-vcs.org/>`_ repositories
+
+:ref:`swh.loader-git <swh-loader-git>`
+    loader for `Git <https://git-scm.com/>`_ repositories
+
+:ref:`swh.loader-mercurial <swh-loader-mercurial>`
+    loader for `Mercurial <https://www.mercurial-scm.org/>`_ repositories
+
+:ref:`swh.loader-metadata <swh-loader-metadata>`
+    pseudo-loader, which fetches :term:`extrinsic metadata` from forges instead
+    of software artifacts
+
+:ref:`swh.loader-svn <swh-loader-svn>`
+    loader for `Subversion <https://subversion.apache.org/>`_ repositories
+
+:ref:`swh.loader-cvs <swh-loader-cvs>`
+    loader for `CVS <https://savannah.nongnu.org/projects/cvs>`_ repositories
+
+:ref:`swh.model <swh-model>`
+    implementation of the :ref:`data-model` to archive source code artifacts
+
+:ref:`swh.objstorage <swh-objstorage>`
+    content-addressable object storage
+
+:ref:`swh.objstorage.replayer <swh-objstorage-replayer>`
+    Object storage replication tool
+
+:ref:`swh.perfecthash <swh-perfecthash>`
+     Low level management for read-only content-addressable object storage
+     indexed with a perfect hash table
+
+:ref:`swh.scanner <swh-scanner>`
+    source code scanner to analyze code bases and compare them with source code
+    artifacts archived by Software Heritage
+
+:ref:`swh.scheduler <swh-scheduler>`
+    task manager for asynchronous/delayed tasks, used for recurrent (e.g.,
+    listing a forge, loading new stuff from a Git repository) and one-off
+    activities (e.g., loading a specific version of a source package)
+
+:ref:`swh.scrubber <swh-scrubber>`
+    Tooling to check integrity of various data stores (swh.journal, swh.objstorage,
+    swh.storage) and fix corrupt objects they contain.
+
+:ref:`swh.search <swh-search>`
+    search engine for the archive
+
+:ref:`swh.storage <swh-storage>`
+    abstraction layer over the archive, allowing to access all stored source
+    code artifacts as well as their metadata
+
+:ref:`swh.vault <swh-vault>`
+    implementation of the vault service, allowing to retrieve parts of the
+    archive as self-contained bundles (e.g., individual releases, entire
+    repository snapshots, etc.)
+
+:ref:`swh.web <swh-web>`
+    Web application(s) to browse the archive, for both interactive (HTML UI)
+    and mechanized (REST API) use
+
+:ref:`swh.web.client <swh-web-client>`
+    Python client for :ref:`swh.web <swh-web>`
+
+
+Dependencies
+^^^^^^^^^^^^
+
+The dependency relationships among the various modules are depicted below.
+
+.. _py-deps-swh:
+.. figure:: images/py-deps-swh.svg
+   :width: 1024px
+   :align: center
+
+   Dependencies among top-level Python modules (click to zoom).
+
+
+Archive
+^^^^^^^
+
+* :ref:`Archive ChangeLog <archive-changelog>`: notable changes to the archive
+  over time
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   getting-started/index
+   architecture/index
+   contributing/index
+   tutorials/index
+   faq/index
+   roadmap/roadmap-2022
+   roadmap/index
+   api-reference
+   archive-changelog
+   journal
+   statsd
+
+
+.. only:: devel_doc
+
+   Indices and tables
+   ------------------
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`routingtable`
+   * :ref:`search`
+   * :ref:`glossary`
+
diff --git a/docs/infrastructure.rst b/docs/devel/infrastructure.rst
similarity index 100%
rename from docs/infrastructure.rst
rename to docs/devel/infrastructure.rst
diff --git a/docs/journal.rst b/docs/devel/journal.rst
similarity index 100%
rename from docs/journal.rst
rename to docs/devel/journal.rst
diff --git a/docs/keycloak.rst b/docs/devel/keycloak.rst
similarity index 100%
rename from docs/keycloak.rst
rename to docs/devel/keycloak.rst
diff --git a/docs/mirror.rst b/docs/devel/mirror.rst
similarity index 100%
rename from docs/mirror.rst
rename to docs/devel/mirror.rst
diff --git a/docs/roadmap/index.rst b/docs/devel/roadmap/index.rst
similarity index 100%
rename from docs/roadmap/index.rst
rename to docs/devel/roadmap/index.rst
diff --git a/docs/roadmap/roadmap-2021.rst b/docs/devel/roadmap/roadmap-2021.rst
similarity index 100%
rename from docs/roadmap/roadmap-2021.rst
rename to docs/devel/roadmap/roadmap-2021.rst
diff --git a/docs/roadmap/roadmap-2022.rst b/docs/devel/roadmap/roadmap-2022.rst
similarity index 100%
rename from docs/roadmap/roadmap-2022.rst
rename to docs/devel/roadmap/roadmap-2022.rst
diff --git a/docs/services.txt b/docs/devel/services.txt
similarity index 100%
rename from docs/services.txt
rename to docs/devel/services.txt
diff --git a/docs/statsd.rst b/docs/devel/statsd.rst
similarity index 100%
rename from docs/statsd.rst
rename to docs/devel/statsd.rst
diff --git a/docs/swh-loader.rst b/docs/devel/swh-loader.rst
similarity index 100%
rename from docs/swh-loader.rst
rename to docs/devel/swh-loader.rst
diff --git a/docs/tutorials/add-new-package.rst b/docs/devel/tutorials/add-new-package.rst
similarity index 100%
rename from docs/tutorials/add-new-package.rst
rename to docs/devel/tutorials/add-new-package.rst
diff --git a/docs/tutorials/index.rst b/docs/devel/tutorials/index.rst
similarity index 100%
rename from docs/tutorials/index.rst
rename to docs/devel/tutorials/index.rst
diff --git a/docs/tutorials/issue-debugging-monitoring.md b/docs/devel/tutorials/issue-debugging-monitoring.md
similarity index 100%
rename from docs/tutorials/issue-debugging-monitoring.md
rename to docs/devel/tutorials/issue-debugging-monitoring.md
diff --git a/docs/tutorials/testing.rst b/docs/devel/tutorials/testing.rst
similarity index 100%
rename from docs/tutorials/testing.rst
rename to docs/devel/tutorials/testing.rst
diff --git a/docs/getting-started/using-docker.rst b/docs/getting-started/using-docker.rst
deleted file mode 100644
index 06fda432..00000000
--- a/docs/getting-started/using-docker.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-.. _docker-environment:
-
-.. include:: ../../../docker/README.rst
diff --git a/docs/index.rst b/docs/index.rst
index 8e0ee9f4..6cee18e4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,240 +1,21 @@
 .. _swh-docs:
 
-Software Heritage - Development Documentation
-=============================================
+Software Heritage documentation
+===============================
 
-Getting started
----------------
-
-* :ref:`getting-started` → deploy a local copy of the Software Heritage
-  software stack in less than 5 minutes, or
-* :ref:`developer-setup` → get a working development setup that allows to hack
-  on the Software Heritage software stack
-* :ref:`faq`
-
-Contributing
-------------
-
-* :ref:`patch-submission` → learn how to submit your patches to the
-  Software Heritage codebase
-* :ref:`code-review` → rules and guidelines to review code in
-  Software Heritage
-* :ref:`python-style-guide` → how to format the Python code you write
-
-Architecture
-------------
-
-* :ref:`architecture-overview` → get a glimpse of the Software Heritage software
-  architecture
-* :ref:`Metadata workflow <architecture-metadata>` → learn how Software Heritage
-  stores and handles metadata
-
-Data Model and Specifications
------------------------------
-
-* :ref:`persistent-identifiers` Specifications of the SoftWare Heritage persistent IDentifiers (SWHID).
-* :ref:`data-model` Documentation of the main |swh| archive data model.
-* :ref:`journal-specs` Documentation of the Kafka journal of the |swh| archive.
-
-Tutorials
----------
-
-* :ref:`testing-guide`
-* :doc:`/tutorials/issue-debugging-monitoring`
-* :ref:`Listing the content of your favorite forge <lister-tutorial>`
-  and :ref:`running a lister in Docker <run-lister-tutorial>`
-* :ref:`Add a new swh package <tutorial-new-package>`
-* :ref:`doc-contribution`
-
-Roadmap
--------
-
-* Current roadmap: :ref:`roadmap-current`
-* Previous roadmaps
-
-  * :ref:`roadmap-2021`
-
-System Administration
----------------------
-
-* :ref:`Network Infrastructure <swh-sysadm:infrastructure>`
-* :ref:`swh-sysadm:mirror` → learn what a Software Heritage mirror is and how to set up
-  one
-* :ref:`Keycloak <swh-sysadm:keycloak>` → learn how to use Keycloak,
-  the authentication system used by |swh|'s web interface and public APIs
-
-.. _components:
-
-Components
-----------
-
-Here is brief overview of the most relevant software components in the Software
-Heritage stack, in alphabetical order.
-For a better introduction to the architecture, see the :ref:`architecture-overview`,
-which presents each of them in a didactical order.
-
-Each component name is linked to the development documentation
-of the corresponding Python module.
-
-:ref:`swh.auth <swh-auth>`
-    low-level library used by modules needing keycloak authentication
-
-:ref:`swh.core <swh-core>`
-    low-level utilities and helpers used by almost all other modules in the
-    stack
-
-:ref:`swh.counters <swh-counters>`
-    service providing efficient estimates of the number of objects in the SWH archive,
-    using Redis's Hyperloglog
-
-:ref:`swh.dataset <swh-dataset>`
-    public datasets and periodic data dumps of the archive released by Software
-    Heritage
-
-:ref:`swh.deposit <swh-deposit>`
-    push-based deposit of software artifacts to the archive
-
-swh.docs
-    developer documentation (used to generate this doc you are reading)
-
-:ref:`swh.fuse <swh-fuse>`
-    Virtual file system to browse the Software Heritage archive, based on
-    `FUSE <https://github.com/libfuse/libfuse>`_
-
-:ref:`swh.graph <swh-graph>`
-    Fast, compressed, in-memory representation of the archive, with tooling to
-    generate and query it.
-
-:ref:`swh.graphql <swh-graphql>`
-    GraphQL API to request archive data offering more precise and flexible queries
-    than the REST API.
-
-:ref:`swh.indexer <swh-indexer>`
-    tools and workers used to crawl the content of the archive and extract
-    derived information from any artifact stored in it
-
-:ref:`swh.journal <swh-journal>`
-    persistent logger of changes to the archive, with publish-subscribe support
-
-:ref:`swh.lister <swh-lister>`
-    collection of listers for all sorts of source code hosting and distribution
-    places (forges, distributions, package managers, etc.)
-
-:ref:`swh.loader-core <swh-loader-core>`
-    low-level loading utilities and helpers used by all other loaders
-
-:ref:`swh.loader-bzr <swh-loader-bzr>`
-    loader for `Bazaar <http://bazaar.canonical.com/en/>`_ and
-    `Breezy <https://www.breezy-vcs.org/>`_ repositories
-
-:ref:`swh.loader-git <swh-loader-git>`
-    loader for `Git <https://git-scm.com/>`_ repositories
-
-:ref:`swh.loader-mercurial <swh-loader-mercurial>`
-    loader for `Mercurial <https://www.mercurial-scm.org/>`_ repositories
-
-:ref:`swh.loader-metadata <swh-loader-metadata>`
-    pseudo-loader, which fetches :term:`extrinsic metadata` from forges instead
-    of software artifacts
-
-:ref:`swh.loader-svn <swh-loader-svn>`
-    loader for `Subversion <https://subversion.apache.org/>`_ repositories
-
-:ref:`swh.loader-cvs <swh-loader-cvs>`
-    loader for `CVS <https://savannah.nongnu.org/projects/cvs>`_ repositories
-
-:ref:`swh.model <swh-model>`
-    implementation of the :ref:`data-model` to archive source code artifacts
-
-:ref:`swh.objstorage <swh-objstorage>`
-    content-addressable object storage
-
-:ref:`swh.objstorage.replayer <swh-objstorage-replayer>`
-    Object storage replication tool
-
-:ref:`swh.perfecthash <swh-perfecthash>`
-     Low level management for read-only content-addressable object storage
-     indexed with a perfect hash table
-
-:ref:`swh.scanner <swh-scanner>`
-    source code scanner to analyze code bases and compare them with source code
-    artifacts archived by Software Heritage
-
-:ref:`swh.scheduler <swh-scheduler>`
-    task manager for asynchronous/delayed tasks, used for recurrent (e.g.,
-    listing a forge, loading new stuff from a Git repository) and one-off
-    activities (e.g., loading a specific version of a source package)
-
-:ref:`swh.scrubber <swh-scrubber>`
-    Tooling to check integrity of various data stores (swh.journal, swh.objstorage,
-    swh.storage) and fix corrupt objects they contain.
-
-:ref:`swh.search <swh-search>`
-    search engine for the archive
-
-:ref:`swh.storage <swh-storage>`
-    abstraction layer over the archive, allowing to access all stored source
-    code artifacts as well as their metadata
-
-:ref:`swh.vault <swh-vault>`
-    implementation of the vault service, allowing to retrieve parts of the
-    archive as self-contained bundles (e.g., individual releases, entire
-    repository snapshots, etc.)
-
-:ref:`swh.web <swh-web>`
-    Web application(s) to browse the archive, for both interactive (HTML UI)
-    and mechanized (REST API) use
-
-:ref:`swh.web.client <swh-web-client>`
-    Python client for :ref:`swh.web <swh-web>`
-
-
-Dependencies
-------------
-
-The dependency relationships among the various modules are depicted below.
-
-.. _py-deps-swh:
-.. figure:: images/py-deps-swh.svg
-   :width: 1024px
-   :align: center
-
-   Dependencies among top-level Python modules (click to zoom).
-
-
-Archive
--------
-
-* :ref:`Archive ChangeLog <archive-changelog>`: notable changes to the archive
-  over time
+.. toctree::
+  :maxdepth: 1
+  :caption: Contents:
 
+  devel/index
+  sysadm/index
+  user/index
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* `URLs index <http-routingtable.html>`_
+* :ref:`routingtable`
 * :ref:`search`
 * :ref:`glossary`
-
-
-.. ensure sphinx does not complain about index files not being included
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-   :titlesonly:
-   :hidden:
-
-   getting-started/index
-   architecture/index
-   contributing/index
-   tutorials/index
-   faq/index
-   roadmap/roadmap-2022
-   roadmap/index
-   api-reference
-   archive-changelog
-   journal
-   statsd
diff --git a/sysadm/.gitignore b/docs/sysadm/.gitignore
similarity index 100%
rename from sysadm/.gitignore
rename to docs/sysadm/.gitignore
diff --git a/sysadm/Makefile b/docs/sysadm/Makefile
similarity index 76%
rename from sysadm/Makefile
rename to docs/sysadm/Makefile
index 1b14801b..9b121624 100644
--- a/sysadm/Makefile
+++ b/docs/sysadm/Makefile
@@ -3,16 +3,12 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -t sysadm_doc
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
+all: html
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
@@ -28,3 +24,5 @@ html: sphinx/html
 clean: sphinx/clean
 	$(MAKE) -C images clean
 	rm -f *-stamp
+
+.PHONY: html clean
\ No newline at end of file
diff --git a/sysadm/_static b/docs/sysadm/_static
similarity index 100%
rename from sysadm/_static
rename to docs/sysadm/_static
diff --git a/sysadm/conf.py b/docs/sysadm/conf.py
similarity index 100%
rename from sysadm/conf.py
rename to docs/sysadm/conf.py
diff --git a/sysadm/data-silos/cassandra/index.rst b/docs/sysadm/data-silos/cassandra/index.rst
similarity index 100%
rename from sysadm/data-silos/cassandra/index.rst
rename to docs/sysadm/data-silos/cassandra/index.rst
diff --git a/sysadm/data-silos/cassandra/installation.rst b/docs/sysadm/data-silos/cassandra/installation.rst
similarity index 100%
rename from sysadm/data-silos/cassandra/installation.rst
rename to docs/sysadm/data-silos/cassandra/installation.rst
diff --git a/sysadm/data-silos/elasticsearch/index.rst b/docs/sysadm/data-silos/elasticsearch/index.rst
similarity index 100%
rename from sysadm/data-silos/elasticsearch/index.rst
rename to docs/sysadm/data-silos/elasticsearch/index.rst
diff --git a/sysadm/data-silos/index.rst b/docs/sysadm/data-silos/index.rst
similarity index 100%
rename from sysadm/data-silos/index.rst
rename to docs/sysadm/data-silos/index.rst
diff --git a/sysadm/data-silos/kafka/index.rst b/docs/sysadm/data-silos/kafka/index.rst
similarity index 100%
rename from sysadm/data-silos/kafka/index.rst
rename to docs/sysadm/data-silos/kafka/index.rst
diff --git a/sysadm/data-silos/kafka/manage-topics.rst b/docs/sysadm/data-silos/kafka/manage-topics.rst
similarity index 100%
rename from sysadm/data-silos/kafka/manage-topics.rst
rename to docs/sysadm/data-silos/kafka/manage-topics.rst
diff --git a/sysadm/data-silos/postgresql/backup.rst b/docs/sysadm/data-silos/postgresql/backup.rst
similarity index 100%
rename from sysadm/data-silos/postgresql/backup.rst
rename to docs/sysadm/data-silos/postgresql/backup.rst
diff --git a/sysadm/data-silos/postgresql/howto-connect.rst b/docs/sysadm/data-silos/postgresql/howto-connect.rst
similarity index 100%
rename from sysadm/data-silos/postgresql/howto-connect.rst
rename to docs/sysadm/data-silos/postgresql/howto-connect.rst
diff --git a/sysadm/data-silos/postgresql/index.rst b/docs/sysadm/data-silos/postgresql/index.rst
similarity index 100%
rename from sysadm/data-silos/postgresql/index.rst
rename to docs/sysadm/data-silos/postgresql/index.rst
diff --git a/sysadm/deployment/argocd.rst b/docs/sysadm/deployment/argocd.rst
similarity index 100%
rename from sysadm/deployment/argocd.rst
rename to docs/sysadm/deployment/argocd.rst
diff --git a/sysadm/deployment/deploy-lister.rst b/docs/sysadm/deployment/deploy-lister.rst
similarity index 100%
rename from sysadm/deployment/deploy-lister.rst
rename to docs/sysadm/deployment/deploy-lister.rst
diff --git a/sysadm/deployment/deployment-environments.rst b/docs/sysadm/deployment/deployment-environments.rst
similarity index 100%
rename from sysadm/deployment/deployment-environments.rst
rename to docs/sysadm/deployment/deployment-environments.rst
diff --git a/sysadm/deployment/howto-debian-packaging.rst b/docs/sysadm/deployment/howto-debian-packaging.rst
similarity index 100%
rename from sysadm/deployment/howto-debian-packaging.rst
rename to docs/sysadm/deployment/howto-debian-packaging.rst
diff --git a/sysadm/deployment/howto-process-add-forge-now-requests.rst b/docs/sysadm/deployment/howto-process-add-forge-now-requests.rst
similarity index 100%
rename from sysadm/deployment/howto-process-add-forge-now-requests.rst
rename to docs/sysadm/deployment/howto-process-add-forge-now-requests.rst
diff --git a/sysadm/deployment/index.rst b/docs/sysadm/deployment/index.rst
similarity index 100%
rename from sysadm/deployment/index.rst
rename to docs/sysadm/deployment/index.rst
diff --git a/sysadm/deployment/jenkins.rst b/docs/sysadm/deployment/jenkins.rst
similarity index 100%
rename from sysadm/deployment/jenkins.rst
rename to docs/sysadm/deployment/jenkins.rst
diff --git a/sysadm/deployment/storage-database-migration.rst b/docs/sysadm/deployment/storage-database-migration.rst
similarity index 100%
rename from sysadm/deployment/storage-database-migration.rst
rename to docs/sysadm/deployment/storage-database-migration.rst
diff --git a/sysadm/deployment/upgrade-swh-service.rst b/docs/sysadm/deployment/upgrade-swh-service.rst
similarity index 100%
rename from sysadm/deployment/upgrade-swh-service.rst
rename to docs/sysadm/deployment/upgrade-swh-service.rst
diff --git a/sysadm/getting-started/index.rst b/docs/sysadm/getting-started/index.rst
similarity index 100%
rename from sysadm/getting-started/index.rst
rename to docs/sysadm/getting-started/index.rst
diff --git a/sysadm/getting-started/setup-repositories.rst b/docs/sysadm/getting-started/setup-repositories.rst
similarity index 100%
rename from sysadm/getting-started/setup-repositories.rst
rename to docs/sysadm/getting-started/setup-repositories.rst
diff --git a/sysadm/images/.gitignore b/docs/sysadm/images/.gitignore
similarity index 100%
rename from sysadm/images/.gitignore
rename to docs/sysadm/images/.gitignore
diff --git a/sysadm/images/Makefile b/docs/sysadm/images/Makefile
similarity index 100%
rename from sysadm/images/Makefile
rename to docs/sysadm/images/Makefile
diff --git a/sysadm/images/gitlab-infrastructure.png b/docs/sysadm/images/gitlab-infrastructure.png
similarity index 100%
rename from sysadm/images/gitlab-infrastructure.png
rename to docs/sysadm/images/gitlab-infrastructure.png
diff --git a/sysadm/images/infrastructure/network/carp_maintenance.png b/docs/sysadm/images/infrastructure/network/carp_maintenance.png
similarity index 100%
rename from sysadm/images/infrastructure/network/carp_maintenance.png
rename to docs/sysadm/images/infrastructure/network/carp_maintenance.png
diff --git a/sysadm/images/infrastructure/network/check_for_upgrade.png b/docs/sysadm/images/infrastructure/network/check_for_upgrade.png
similarity index 100%
rename from sysadm/images/infrastructure/network/check_for_upgrade.png
rename to docs/sysadm/images/infrastructure/network/check_for_upgrade.png
diff --git a/sysadm/images/infrastructure/network/proceed_update.png b/docs/sysadm/images/infrastructure/network/proceed_update.png
similarity index 100%
rename from sysadm/images/infrastructure/network/proceed_update.png
rename to docs/sysadm/images/infrastructure/network/proceed_update.png
diff --git a/sysadm/images/infrastructure/network/reactivate_carp.png b/docs/sysadm/images/infrastructure/network/reactivate_carp.png
similarity index 100%
rename from sysadm/images/infrastructure/network/reactivate_carp.png
rename to docs/sysadm/images/infrastructure/network/reactivate_carp.png
diff --git a/sysadm/images/infrastructure/network/sync.png b/docs/sysadm/images/infrastructure/network/sync.png
similarity index 100%
rename from sysadm/images/infrastructure/network/sync.png
rename to docs/sysadm/images/infrastructure/network/sync.png
diff --git a/sysadm/images/jenkins/300px-build-button.png b/docs/sysadm/images/jenkins/300px-build-button.png
similarity index 100%
rename from sysadm/images/jenkins/300px-build-button.png
rename to docs/sysadm/images/jenkins/300px-build-button.png
diff --git a/sysadm/images/jenkins/300px-replay.png b/docs/sysadm/images/jenkins/300px-replay.png
similarity index 100%
rename from sysadm/images/jenkins/300px-replay.png
rename to docs/sysadm/images/jenkins/300px-replay.png
diff --git a/sysadm/images/jenkins/300px-restart-from-stage.png b/docs/sysadm/images/jenkins/300px-restart-from-stage.png
similarity index 100%
rename from sysadm/images/jenkins/300px-restart-from-stage.png
rename to docs/sysadm/images/jenkins/300px-restart-from-stage.png
diff --git a/sysadm/images/jenkins/diff-report.png b/docs/sysadm/images/jenkins/diff-report.png
similarity index 100%
rename from sysadm/images/jenkins/diff-report.png
rename to docs/sysadm/images/jenkins/diff-report.png
diff --git a/sysadm/images/jenkins/revision-report.png b/docs/sysadm/images/jenkins/revision-report.png
similarity index 100%
rename from sysadm/images/jenkins/revision-report.png
rename to docs/sysadm/images/jenkins/revision-report.png
diff --git a/sysadm/images/keycloak_add_user_01.jpg b/docs/sysadm/images/keycloak_add_user_01.jpg
similarity index 100%
rename from sysadm/images/keycloak_add_user_01.jpg
rename to docs/sysadm/images/keycloak_add_user_01.jpg
diff --git a/sysadm/images/keycloak_add_user_02.jpg b/docs/sysadm/images/keycloak_add_user_02.jpg
similarity index 100%
rename from sysadm/images/keycloak_add_user_02.jpg
rename to docs/sysadm/images/keycloak_add_user_02.jpg
diff --git a/sysadm/images/keycloak_add_user_03.jpg b/docs/sysadm/images/keycloak_add_user_03.jpg
similarity index 100%
rename from sysadm/images/keycloak_add_user_03.jpg
rename to docs/sysadm/images/keycloak_add_user_03.jpg
diff --git a/sysadm/images/keycloak_add_user_permission_01.jpg b/docs/sysadm/images/keycloak_add_user_permission_01.jpg
similarity index 100%
rename from sysadm/images/keycloak_add_user_permission_01.jpg
rename to docs/sysadm/images/keycloak_add_user_permission_01.jpg
diff --git a/sysadm/images/keycloak_add_user_permission_02.jpg b/docs/sysadm/images/keycloak_add_user_permission_02.jpg
similarity index 100%
rename from sysadm/images/keycloak_add_user_permission_02.jpg
rename to docs/sysadm/images/keycloak_add_user_permission_02.jpg
diff --git a/sysadm/images/keycloak_add_user_permission_03.jpg b/docs/sysadm/images/keycloak_add_user_permission_03.jpg
similarity index 100%
rename from sysadm/images/keycloak_add_user_permission_03.jpg
rename to docs/sysadm/images/keycloak_add_user_permission_03.jpg
diff --git a/sysadm/images/keycloak_add_user_permission_04.jpg b/docs/sysadm/images/keycloak_add_user_permission_04.jpg
similarity index 100%
rename from sysadm/images/keycloak_add_user_permission_04.jpg
rename to docs/sysadm/images/keycloak_add_user_permission_04.jpg
diff --git a/sysadm/images/mirror-architecture.svg b/docs/sysadm/images/mirror-architecture.svg
similarity index 100%
rename from sysadm/images/mirror-architecture.svg
rename to docs/sysadm/images/mirror-architecture.svg
diff --git a/sysadm/images/network.uml b/docs/sysadm/images/network.uml
similarity index 100%
rename from sysadm/images/network.uml
rename to docs/sysadm/images/network.uml
diff --git a/sysadm/images/openvpn/nm-openvpn-advanced-general.png b/docs/sysadm/images/openvpn/nm-openvpn-advanced-general.png
similarity index 100%
rename from sysadm/images/openvpn/nm-openvpn-advanced-general.png
rename to docs/sysadm/images/openvpn/nm-openvpn-advanced-general.png
diff --git a/sysadm/images/openvpn/nm-openvpn-advanced-security.png b/docs/sysadm/images/openvpn/nm-openvpn-advanced-security.png
similarity index 100%
rename from sysadm/images/openvpn/nm-openvpn-advanced-security.png
rename to docs/sysadm/images/openvpn/nm-openvpn-advanced-security.png
diff --git a/sysadm/images/openvpn/nm-openvpn-advanced-tls-auth.png b/docs/sysadm/images/openvpn/nm-openvpn-advanced-tls-auth.png
similarity index 100%
rename from sysadm/images/openvpn/nm-openvpn-advanced-tls-auth.png
rename to docs/sysadm/images/openvpn/nm-openvpn-advanced-tls-auth.png
diff --git a/sysadm/images/openvpn/nm-openvpn-base.png b/docs/sysadm/images/openvpn/nm-openvpn-base.png
similarity index 100%
rename from sysadm/images/openvpn/nm-openvpn-base.png
rename to docs/sysadm/images/openvpn/nm-openvpn-base.png
diff --git a/sysadm/images/openvpn/nm-openvpn-routes.png b/docs/sysadm/images/openvpn/nm-openvpn-routes.png
similarity index 100%
rename from sysadm/images/openvpn/nm-openvpn-routes.png
rename to docs/sysadm/images/openvpn/nm-openvpn-routes.png
diff --git a/sysadm/images/openvpn/vpn-csr-certificate.png b/docs/sysadm/images/openvpn/vpn-csr-certificate.png
similarity index 100%
rename from sysadm/images/openvpn/vpn-csr-certificate.png
rename to docs/sysadm/images/openvpn/vpn-csr-certificate.png
diff --git a/sysadm/images/openvpn/vpn-csr-signing.png b/docs/sysadm/images/openvpn/vpn-csr-signing.png
similarity index 100%
rename from sysadm/images/openvpn/vpn-csr-signing.png
rename to docs/sysadm/images/openvpn/vpn-csr-signing.png
diff --git a/sysadm/images/openvpn/vpn-ctrl-list.png b/docs/sysadm/images/openvpn/vpn-ctrl-list.png
similarity index 100%
rename from sysadm/images/openvpn/vpn-ctrl-list.png
rename to docs/sysadm/images/openvpn/vpn-ctrl-list.png
diff --git a/sysadm/images/openvpn/vpn-main-trust-page.png b/docs/sysadm/images/openvpn/vpn-main-trust-page.png
similarity index 100%
rename from sysadm/images/openvpn/vpn-main-trust-page.png
rename to docs/sysadm/images/openvpn/vpn-main-trust-page.png
diff --git a/sysadm/images/staging-environment.uml b/docs/sysadm/images/staging-environment.uml
similarity index 100%
rename from sysadm/images/staging-environment.uml
rename to docs/sysadm/images/staging-environment.uml
diff --git a/sysadm/index.rst b/docs/sysadm/index.rst
similarity index 58%
rename from sysadm/index.rst
rename to docs/sysadm/index.rst
index b38cf1b1..bbc051bf 100644
--- a/sysadm/index.rst
+++ b/docs/sysadm/index.rst
@@ -1,5 +1,7 @@
-Welcome to the Software Heritage sysadmin documentation
-=======================================================
+.. _swh-docs-sysadm:
+
+Software Heritage - Sysadmin Documentation
+==========================================
 
 .. toctree::
    :maxdepth: 2
@@ -16,9 +18,10 @@ Welcome to the Software Heritage sysadmin documentation
    mirror-operations/index
    support-services/index
 
+.. only:: sysadm_doc
 
-Indices and tables
-==================
+   Indices and tables
+   ------------------
 
-* :ref:`genindex`
-* :ref:`search`
+   * :ref:`genindex`
+   * :ref:`search`
diff --git a/sysadm/life-cycle-management/how-to-manage-tools-upgrades.rst b/docs/sysadm/life-cycle-management/how-to-manage-tools-upgrades.rst
similarity index 98%
rename from sysadm/life-cycle-management/how-to-manage-tools-upgrades.rst
rename to docs/sysadm/life-cycle-management/how-to-manage-tools-upgrades.rst
index a2f7b6c9..26081c42 100644
--- a/sysadm/life-cycle-management/how-to-manage-tools-upgrades.rst
+++ b/docs/sysadm/life-cycle-management/how-to-manage-tools-upgrades.rst
@@ -22,7 +22,7 @@ SWH components
 +========================+======================+========================+============================================================+=======+
 | kafka                  | 2.6.0                | 3.0.0                  | yes a lot of cve were fixed and it is an exposed service   |       |
 +------------------------+----------------------+------------------------+------------------------------------------------------------+-------+
-| Elasticsearch (search) | 7.15.2               | 7.16                   | we should follow the mouvement to avoid accumulating delay |       |
+| Elasticsearch (search) | 7.15.2               | 7.16                   | we should follow the movement to avoid accumulating delay  |       |
 +------------------------+----------------------+------------------------+------------------------------------------------------------+-------+
 | redis                  | 5.0.3                | 6.2.6                  | N/A debian package                                         |       |
 +------------------------+----------------------+------------------------+------------------------------------------------------------+-------+
diff --git a/sysadm/life-cycle-management/how-to-new-service-backup.rst b/docs/sysadm/life-cycle-management/how-to-new-service-backup.rst
similarity index 100%
rename from sysadm/life-cycle-management/how-to-new-service-backup.rst
rename to docs/sysadm/life-cycle-management/how-to-new-service-backup.rst
diff --git a/sysadm/life-cycle-management/index.rst b/docs/sysadm/life-cycle-management/index.rst
similarity index 100%
rename from sysadm/life-cycle-management/index.rst
rename to docs/sysadm/life-cycle-management/index.rst
diff --git a/sysadm/make.bat b/docs/sysadm/make.bat
similarity index 100%
rename from sysadm/make.bat
rename to docs/sysadm/make.bat
diff --git a/sysadm/mirror-operations/deploy.rst b/docs/sysadm/mirror-operations/deploy.rst
similarity index 100%
rename from sysadm/mirror-operations/deploy.rst
rename to docs/sysadm/mirror-operations/deploy.rst
diff --git a/sysadm/mirror-operations/docker.rst b/docs/sysadm/mirror-operations/docker.rst
similarity index 99%
rename from sysadm/mirror-operations/docker.rst
rename to docs/sysadm/mirror-operations/docker.rst
index 33705a42..42214f8d 100644
--- a/sysadm/mirror-operations/docker.rst
+++ b/docs/sysadm/mirror-operations/docker.rst
@@ -8,8 +8,8 @@ Deploy a Software Heritage stack with docker deploy
 
    mirror operators
 
-Prerequisities
---------------
+Prerequisites
+-------------
 
 We assume that you have a properly set up docker swarm cluster with support for
 the `docker stack deploy
diff --git a/sysadm/mirror-operations/index.rst b/docs/sysadm/mirror-operations/index.rst
similarity index 100%
rename from sysadm/mirror-operations/index.rst
rename to docs/sysadm/mirror-operations/index.rst
diff --git a/sysadm/mirror-operations/monitor.rst b/docs/sysadm/mirror-operations/monitor.rst
similarity index 100%
rename from sysadm/mirror-operations/monitor.rst
rename to docs/sysadm/mirror-operations/monitor.rst
diff --git a/sysadm/mirror-operations/onboard.rst b/docs/sysadm/mirror-operations/onboard.rst
similarity index 100%
rename from sysadm/mirror-operations/onboard.rst
rename to docs/sysadm/mirror-operations/onboard.rst
diff --git a/sysadm/mirror-operations/planning.rst b/docs/sysadm/mirror-operations/planning.rst
similarity index 100%
rename from sysadm/mirror-operations/planning.rst
rename to docs/sysadm/mirror-operations/planning.rst
diff --git a/sysadm/network-architecture/dns.rst b/docs/sysadm/network-architecture/dns.rst
similarity index 100%
rename from sysadm/network-architecture/dns.rst
rename to docs/sysadm/network-architecture/dns.rst
diff --git a/sysadm/network-architecture/how-to-access-firewall-nodes-without-vpn.rst b/docs/sysadm/network-architecture/how-to-access-firewall-nodes-without-vpn.rst
similarity index 100%
rename from sysadm/network-architecture/how-to-access-firewall-nodes-without-vpn.rst
rename to docs/sysadm/network-architecture/how-to-access-firewall-nodes-without-vpn.rst
diff --git a/sysadm/network-architecture/how-to-access-firewall-settings.rst b/docs/sysadm/network-architecture/how-to-access-firewall-settings.rst
similarity index 98%
rename from sysadm/network-architecture/how-to-access-firewall-settings.rst
rename to docs/sysadm/network-architecture/how-to-access-firewall-settings.rst
index 8e4927d2..6532f246 100644
--- a/sysadm/network-architecture/how-to-access-firewall-settings.rst
+++ b/docs/sysadm/network-architecture/how-to-access-firewall-settings.rst
@@ -33,7 +33,7 @@ Access to the gui of the secondary firewall
 -------------------------------------------
 
 The secondary firewall is not directly reachable for VPN user. As the OpenVPN service is
-also running when the firewall is a backup, the packets coming from tne VPN are routed
+also running when the firewall is a backup, the packets coming from the VPN are routed
 to the local VPN on the secondary and lost.
 
 To access to GUI, a tunnel can be used:
diff --git a/sysadm/network-architecture/how-to-upgrade-firewall-os.rst b/docs/sysadm/network-architecture/how-to-upgrade-firewall-os.rst
similarity index 100%
rename from sysadm/network-architecture/how-to-upgrade-firewall-os.rst
rename to docs/sysadm/network-architecture/how-to-upgrade-firewall-os.rst
diff --git a/sysadm/network-architecture/idrac.rst b/docs/sysadm/network-architecture/idrac.rst
similarity index 100%
rename from sysadm/network-architecture/idrac.rst
rename to docs/sysadm/network-architecture/idrac.rst
diff --git a/sysadm/network-architecture/index.rst b/docs/sysadm/network-architecture/index.rst
similarity index 100%
rename from sysadm/network-architecture/index.rst
rename to docs/sysadm/network-architecture/index.rst
diff --git a/sysadm/network-architecture/reference-network-configuration.rst b/docs/sysadm/network-architecture/reference-network-configuration.rst
similarity index 100%
rename from sysadm/network-architecture/reference-network-configuration.rst
rename to docs/sysadm/network-architecture/reference-network-configuration.rst
diff --git a/sysadm/network-architecture/service-urls.rst b/docs/sysadm/network-architecture/service-urls.rst
similarity index 100%
rename from sysadm/network-architecture/service-urls.rst
rename to docs/sysadm/network-architecture/service-urls.rst
diff --git a/sysadm/puppet/howto-deploy-puppet-change.rst b/docs/sysadm/puppet/howto-deploy-puppet-change.rst
similarity index 100%
rename from sysadm/puppet/howto-deploy-puppet-change.rst
rename to docs/sysadm/puppet/howto-deploy-puppet-change.rst
diff --git a/sysadm/puppet/howto-manage-third-party-modules.rst b/docs/sysadm/puppet/howto-manage-third-party-modules.rst
similarity index 100%
rename from sysadm/puppet/howto-manage-third-party-modules.rst
rename to docs/sysadm/puppet/howto-manage-third-party-modules.rst
diff --git a/sysadm/puppet/howto-renew-agent-certificate.rst b/docs/sysadm/puppet/howto-renew-agent-certificate.rst
similarity index 100%
rename from sysadm/puppet/howto-renew-agent-certificate.rst
rename to docs/sysadm/puppet/howto-renew-agent-certificate.rst
diff --git a/sysadm/puppet/howto-test-changes-in-vagrant.rst b/docs/sysadm/puppet/howto-test-changes-in-vagrant.rst
similarity index 100%
rename from sysadm/puppet/howto-test-changes-in-vagrant.rst
rename to docs/sysadm/puppet/howto-test-changes-in-vagrant.rst
diff --git a/sysadm/puppet/index.rst b/docs/sysadm/puppet/index.rst
similarity index 100%
rename from sysadm/puppet/index.rst
rename to docs/sysadm/puppet/index.rst
diff --git a/sysadm/puppet/reference-architecture.rst b/docs/sysadm/puppet/reference-architecture.rst
similarity index 100%
rename from sysadm/puppet/reference-architecture.rst
rename to docs/sysadm/puppet/reference-architecture.rst
diff --git a/sysadm/puppet/reference-best-practices.rst b/docs/sysadm/puppet/reference-best-practices.rst
similarity index 100%
rename from sysadm/puppet/reference-best-practices.rst
rename to docs/sysadm/puppet/reference-best-practices.rst
diff --git a/sysadm/puppet/reference-setup.rst b/docs/sysadm/puppet/reference-setup.rst
similarity index 100%
rename from sysadm/puppet/reference-setup.rst
rename to docs/sysadm/puppet/reference-setup.rst
diff --git a/sysadm/puppet/tutorial-my-first-change-in-puppet.rst b/docs/sysadm/puppet/tutorial-my-first-change-in-puppet.rst
similarity index 100%
rename from sysadm/puppet/tutorial-my-first-change-in-puppet.rst
rename to docs/sysadm/puppet/tutorial-my-first-change-in-puppet.rst
diff --git a/sysadm/server-architecture/backups/howto-access-backups.rst b/docs/sysadm/server-architecture/backups/howto-access-backups.rst
similarity index 100%
rename from sysadm/server-architecture/backups/howto-access-backups.rst
rename to docs/sysadm/server-architecture/backups/howto-access-backups.rst
diff --git a/sysadm/server-architecture/backups/index.rst b/docs/sysadm/server-architecture/backups/index.rst
similarity index 100%
rename from sysadm/server-architecture/backups/index.rst
rename to docs/sysadm/server-architecture/backups/index.rst
diff --git a/sysadm/server-architecture/backups/reference-infrastructure.rst b/docs/sysadm/server-architecture/backups/reference-infrastructure.rst
similarity index 100%
rename from sysadm/server-architecture/backups/reference-infrastructure.rst
rename to docs/sysadm/server-architecture/backups/reference-infrastructure.rst
diff --git a/sysadm/server-architecture/howto-install-new-physical-server.rst b/docs/sysadm/server-architecture/howto-install-new-physical-server.rst
similarity index 100%
rename from sysadm/server-architecture/howto-install-new-physical-server.rst
rename to docs/sysadm/server-architecture/howto-install-new-physical-server.rst
diff --git a/sysadm/server-architecture/howto-provision-new-vm.rst b/docs/sysadm/server-architecture/howto-provision-new-vm.rst
similarity index 100%
rename from sysadm/server-architecture/howto-provision-new-vm.rst
rename to docs/sysadm/server-architecture/howto-provision-new-vm.rst
diff --git a/sysadm/server-architecture/howto-search-inventory.rst b/docs/sysadm/server-architecture/howto-search-inventory.rst
similarity index 100%
rename from sysadm/server-architecture/howto-search-inventory.rst
rename to docs/sysadm/server-architecture/howto-search-inventory.rst
diff --git a/sysadm/server-architecture/howto-upgrade-machine.rst b/docs/sysadm/server-architecture/howto-upgrade-machine.rst
similarity index 100%
rename from sysadm/server-architecture/howto-upgrade-machine.rst
rename to docs/sysadm/server-architecture/howto-upgrade-machine.rst
diff --git a/sysadm/server-architecture/index.rst b/docs/sysadm/server-architecture/index.rst
similarity index 100%
rename from sysadm/server-architecture/index.rst
rename to docs/sysadm/server-architecture/index.rst
diff --git a/sysadm/server-architecture/reference-baseline-hardware.rst b/docs/sysadm/server-architecture/reference-baseline-hardware.rst
similarity index 100%
rename from sysadm/server-architecture/reference-baseline-hardware.rst
rename to docs/sysadm/server-architecture/reference-baseline-hardware.rst
diff --git a/sysadm/server-architecture/reference-inventory.rst b/docs/sysadm/server-architecture/reference-inventory.rst
similarity index 100%
rename from sysadm/server-architecture/reference-inventory.rst
rename to docs/sysadm/server-architecture/reference-inventory.rst
diff --git a/sysadm/support-services/gitlab/index.rst b/docs/sysadm/support-services/gitlab/index.rst
similarity index 100%
rename from sysadm/support-services/gitlab/index.rst
rename to docs/sysadm/support-services/gitlab/index.rst
diff --git a/sysadm/support-services/gitlab/installation.rst b/docs/sysadm/support-services/gitlab/installation.rst
similarity index 100%
rename from sysadm/support-services/gitlab/installation.rst
rename to docs/sysadm/support-services/gitlab/installation.rst
diff --git a/sysadm/support-services/index.rst b/docs/sysadm/support-services/index.rst
similarity index 100%
rename from sysadm/support-services/index.rst
rename to docs/sysadm/support-services/index.rst
diff --git a/sysadm/user-management/how-to-manage-creds-store.rst b/docs/sysadm/user-management/how-to-manage-creds-store.rst
similarity index 100%
rename from sysadm/user-management/how-to-manage-creds-store.rst
rename to docs/sysadm/user-management/how-to-manage-creds-store.rst
diff --git a/sysadm/user-management/index.rst b/docs/sysadm/user-management/index.rst
similarity index 100%
rename from sysadm/user-management/index.rst
rename to docs/sysadm/user-management/index.rst
diff --git a/sysadm/user-management/keycloak/authentication.rst b/docs/sysadm/user-management/keycloak/authentication.rst
similarity index 100%
rename from sysadm/user-management/keycloak/authentication.rst
rename to docs/sysadm/user-management/keycloak/authentication.rst
diff --git a/sysadm/user-management/keycloak/how-to-set-user-perms.rst b/docs/sysadm/user-management/keycloak/how-to-set-user-perms.rst
similarity index 100%
rename from sysadm/user-management/keycloak/how-to-set-user-perms.rst
rename to docs/sysadm/user-management/keycloak/how-to-set-user-perms.rst
diff --git a/sysadm/user-management/keycloak/index.rst b/docs/sysadm/user-management/keycloak/index.rst
similarity index 100%
rename from sysadm/user-management/keycloak/index.rst
rename to docs/sysadm/user-management/keycloak/index.rst
diff --git a/sysadm/user-management/onboarding.rst b/docs/sysadm/user-management/onboarding.rst
similarity index 100%
rename from sysadm/user-management/onboarding.rst
rename to docs/sysadm/user-management/onboarding.rst
diff --git a/sysadm/user-management/openvpn/index.rst b/docs/sysadm/user-management/openvpn/index.rst
similarity index 100%
rename from sysadm/user-management/openvpn/index.rst
rename to docs/sysadm/user-management/openvpn/index.rst
diff --git a/sysadm/user-management/openvpn/openvpn.rst b/docs/sysadm/user-management/openvpn/openvpn.rst
similarity index 100%
rename from sysadm/user-management/openvpn/openvpn.rst
rename to docs/sysadm/user-management/openvpn/openvpn.rst
diff --git a/sysadm/user-management/openvpn/softwareheritage-ca-crt.rst b/docs/sysadm/user-management/openvpn/softwareheritage-ca-crt.rst
similarity index 100%
rename from sysadm/user-management/openvpn/softwareheritage-ca-crt.rst
rename to docs/sysadm/user-management/openvpn/softwareheritage-ca-crt.rst
diff --git a/sysadm/user-management/outboarding.rst b/docs/sysadm/user-management/outboarding.rst
similarity index 100%
rename from sysadm/user-management/outboarding.rst
rename to docs/sysadm/user-management/outboarding.rst
diff --git a/user/.gitignore b/docs/user/.gitignore
similarity index 100%
rename from user/.gitignore
rename to docs/user/.gitignore
diff --git a/user/Makefile b/docs/user/Makefile
similarity index 58%
rename from user/Makefile
rename to docs/user/Makefile
index d4bb2cbb..4eaea5ba 100644
--- a/user/Makefile
+++ b/docs/user/Makefile
@@ -3,18 +3,20 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -t sysadm_doc
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
+all: html
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+sphinx/%: Makefile
+	@$(SPHINXBUILD) -M $* "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html: sphinx/html
+
+clean: sphinx/clean
+
+.PHONY: html clean
diff --git a/user/_static b/docs/user/_static
similarity index 100%
rename from user/_static
rename to docs/user/_static
diff --git a/user/conf.py b/docs/user/conf.py
similarity index 100%
rename from user/conf.py
rename to docs/user/conf.py
diff --git a/user/faq/index.rst b/docs/user/faq/index.rst
similarity index 99%
rename from user/faq/index.rst
rename to docs/user/faq/index.rst
index af6fb993..730f6df3 100644
--- a/user/faq/index.rst
+++ b/docs/user/faq/index.rst
@@ -1,4 +1,4 @@
-.. _faq:
+.. _faq_user:
 
 Frequently Asked Questions
 **************************
diff --git a/docs/user/index.rst b/docs/user/index.rst
new file mode 100644
index 00000000..4b58bcc7
--- /dev/null
+++ b/docs/user/index.rst
@@ -0,0 +1,22 @@
+.. _swh-docs-user:
+
+Software Heritage - User Documentation
+======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   faq/index
+   listers/index
+   loaders/index
+   save_code_now/webhooks/index
+
+.. only:: user_doc
+
+   Indices and tables
+   ------------------
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`
diff --git a/user/listers/arch.rst b/docs/user/listers/arch.rst
similarity index 100%
rename from user/listers/arch.rst
rename to docs/user/listers/arch.rst
diff --git a/user/listers/aur.rst b/docs/user/listers/aur.rst
similarity index 100%
rename from user/listers/aur.rst
rename to docs/user/listers/aur.rst
diff --git a/user/listers/bitbucket.rst b/docs/user/listers/bitbucket.rst
similarity index 100%
rename from user/listers/bitbucket.rst
rename to docs/user/listers/bitbucket.rst
diff --git a/user/listers/bower.rst b/docs/user/listers/bower.rst
similarity index 100%
rename from user/listers/bower.rst
rename to docs/user/listers/bower.rst
diff --git a/user/listers/cgit.rst b/docs/user/listers/cgit.rst
similarity index 100%
rename from user/listers/cgit.rst
rename to docs/user/listers/cgit.rst
diff --git a/user/listers/conda.rst b/docs/user/listers/conda.rst
similarity index 100%
rename from user/listers/conda.rst
rename to docs/user/listers/conda.rst
diff --git a/user/listers/cpan.rst b/docs/user/listers/cpan.rst
similarity index 100%
rename from user/listers/cpan.rst
rename to docs/user/listers/cpan.rst
diff --git a/user/listers/cran.rst b/docs/user/listers/cran.rst
similarity index 100%
rename from user/listers/cran.rst
rename to docs/user/listers/cran.rst
diff --git a/user/listers/crates.rst b/docs/user/listers/crates.rst
similarity index 100%
rename from user/listers/crates.rst
rename to docs/user/listers/crates.rst
diff --git a/user/listers/debian.rst b/docs/user/listers/debian.rst
similarity index 100%
rename from user/listers/debian.rst
rename to docs/user/listers/debian.rst
diff --git a/user/listers/gitea.rst b/docs/user/listers/gitea.rst
similarity index 100%
rename from user/listers/gitea.rst
rename to docs/user/listers/gitea.rst
diff --git a/user/listers/github.rst b/docs/user/listers/github.rst
similarity index 100%
rename from user/listers/github.rst
rename to docs/user/listers/github.rst
diff --git a/user/listers/gitlab.rst b/docs/user/listers/gitlab.rst
similarity index 100%
rename from user/listers/gitlab.rst
rename to docs/user/listers/gitlab.rst
diff --git a/user/listers/gnu.rst b/docs/user/listers/gnu.rst
similarity index 100%
rename from user/listers/gnu.rst
rename to docs/user/listers/gnu.rst
diff --git a/user/listers/gogs.rst b/docs/user/listers/gogs.rst
similarity index 100%
rename from user/listers/gogs.rst
rename to docs/user/listers/gogs.rst
diff --git a/user/listers/golang.rst b/docs/user/listers/golang.rst
similarity index 100%
rename from user/listers/golang.rst
rename to docs/user/listers/golang.rst
diff --git a/user/listers/hackage.rst b/docs/user/listers/hackage.rst
similarity index 100%
rename from user/listers/hackage.rst
rename to docs/user/listers/hackage.rst
diff --git a/user/listers/index.rst b/docs/user/listers/index.rst
similarity index 100%
rename from user/listers/index.rst
rename to docs/user/listers/index.rst
diff --git a/user/listers/launchpad.rst b/docs/user/listers/launchpad.rst
similarity index 100%
rename from user/listers/launchpad.rst
rename to docs/user/listers/launchpad.rst
diff --git a/user/listers/maven.rst b/docs/user/listers/maven.rst
similarity index 100%
rename from user/listers/maven.rst
rename to docs/user/listers/maven.rst
diff --git a/user/listers/npm.rst b/docs/user/listers/npm.rst
similarity index 100%
rename from user/listers/npm.rst
rename to docs/user/listers/npm.rst
diff --git a/user/listers/opam.rst b/docs/user/listers/opam.rst
similarity index 100%
rename from user/listers/opam.rst
rename to docs/user/listers/opam.rst
diff --git a/user/listers/packagist.rst b/docs/user/listers/packagist.rst
similarity index 100%
rename from user/listers/packagist.rst
rename to docs/user/listers/packagist.rst
diff --git a/user/listers/phabricator.rst b/docs/user/listers/phabricator.rst
similarity index 100%
rename from user/listers/phabricator.rst
rename to docs/user/listers/phabricator.rst
diff --git a/user/listers/pubdev.rst b/docs/user/listers/pubdev.rst
similarity index 100%
rename from user/listers/pubdev.rst
rename to docs/user/listers/pubdev.rst
diff --git a/user/listers/puppet.rst b/docs/user/listers/puppet.rst
similarity index 100%
rename from user/listers/puppet.rst
rename to docs/user/listers/puppet.rst
diff --git a/user/listers/pypi.rst b/docs/user/listers/pypi.rst
similarity index 100%
rename from user/listers/pypi.rst
rename to docs/user/listers/pypi.rst
diff --git a/user/listers/rubygems.rst b/docs/user/listers/rubygems.rst
similarity index 100%
rename from user/listers/rubygems.rst
rename to docs/user/listers/rubygems.rst
diff --git a/user/listers/sourceforge.rst b/docs/user/listers/sourceforge.rst
similarity index 100%
rename from user/listers/sourceforge.rst
rename to docs/user/listers/sourceforge.rst
diff --git a/user/listers/tuleap.rst b/docs/user/listers/tuleap.rst
similarity index 100%
rename from user/listers/tuleap.rst
rename to docs/user/listers/tuleap.rst
diff --git a/user/loaders/arch.rst b/docs/user/loaders/arch.rst
similarity index 100%
rename from user/loaders/arch.rst
rename to docs/user/loaders/arch.rst
diff --git a/user/loaders/archive.rst b/docs/user/loaders/archive.rst
similarity index 100%
rename from user/loaders/archive.rst
rename to docs/user/loaders/archive.rst
diff --git a/user/loaders/aur.rst b/docs/user/loaders/aur.rst
similarity index 100%
rename from user/loaders/aur.rst
rename to docs/user/loaders/aur.rst
diff --git a/user/loaders/bazaar.rst b/docs/user/loaders/bazaar.rst
similarity index 100%
rename from user/loaders/bazaar.rst
rename to docs/user/loaders/bazaar.rst
diff --git a/user/loaders/conda.rst b/docs/user/loaders/conda.rst
similarity index 100%
rename from user/loaders/conda.rst
rename to docs/user/loaders/conda.rst
diff --git a/user/loaders/cran.rst b/docs/user/loaders/cran.rst
similarity index 100%
rename from user/loaders/cran.rst
rename to docs/user/loaders/cran.rst
diff --git a/user/loaders/crates.rst b/docs/user/loaders/crates.rst
similarity index 100%
rename from user/loaders/crates.rst
rename to docs/user/loaders/crates.rst
diff --git a/user/loaders/cvs.rst b/docs/user/loaders/cvs.rst
similarity index 100%
rename from user/loaders/cvs.rst
rename to docs/user/loaders/cvs.rst
diff --git a/user/loaders/debian.rst b/docs/user/loaders/debian.rst
similarity index 100%
rename from user/loaders/debian.rst
rename to docs/user/loaders/debian.rst
diff --git a/user/loaders/deposit.rst b/docs/user/loaders/deposit.rst
similarity index 100%
rename from user/loaders/deposit.rst
rename to docs/user/loaders/deposit.rst
diff --git a/user/loaders/git.rst b/docs/user/loaders/git.rst
similarity index 100%
rename from user/loaders/git.rst
rename to docs/user/loaders/git.rst
diff --git a/user/loaders/golang.rst b/docs/user/loaders/golang.rst
similarity index 100%
rename from user/loaders/golang.rst
rename to docs/user/loaders/golang.rst
diff --git a/user/loaders/hackage.rst b/docs/user/loaders/hackage.rst
similarity index 100%
rename from user/loaders/hackage.rst
rename to docs/user/loaders/hackage.rst
diff --git a/user/loaders/index.rst b/docs/user/loaders/index.rst
similarity index 100%
rename from user/loaders/index.rst
rename to docs/user/loaders/index.rst
diff --git a/user/loaders/maven.rst b/docs/user/loaders/maven.rst
similarity index 100%
rename from user/loaders/maven.rst
rename to docs/user/loaders/maven.rst
diff --git a/user/loaders/mercurial.rst b/docs/user/loaders/mercurial.rst
similarity index 100%
rename from user/loaders/mercurial.rst
rename to docs/user/loaders/mercurial.rst
diff --git a/user/loaders/nixguix.rst b/docs/user/loaders/nixguix.rst
similarity index 100%
rename from user/loaders/nixguix.rst
rename to docs/user/loaders/nixguix.rst
diff --git a/user/loaders/npm.rst b/docs/user/loaders/npm.rst
similarity index 100%
rename from user/loaders/npm.rst
rename to docs/user/loaders/npm.rst
diff --git a/user/loaders/opam.rst b/docs/user/loaders/opam.rst
similarity index 100%
rename from user/loaders/opam.rst
rename to docs/user/loaders/opam.rst
diff --git a/user/loaders/pubdev.rst b/docs/user/loaders/pubdev.rst
similarity index 100%
rename from user/loaders/pubdev.rst
rename to docs/user/loaders/pubdev.rst
diff --git a/user/loaders/puppet.rst b/docs/user/loaders/puppet.rst
similarity index 100%
rename from user/loaders/puppet.rst
rename to docs/user/loaders/puppet.rst
diff --git a/user/loaders/pypi.rst b/docs/user/loaders/pypi.rst
similarity index 100%
rename from user/loaders/pypi.rst
rename to docs/user/loaders/pypi.rst
diff --git a/user/loaders/rubygems.rst b/docs/user/loaders/rubygems.rst
similarity index 100%
rename from user/loaders/rubygems.rst
rename to docs/user/loaders/rubygems.rst
diff --git a/user/loaders/subversion.rst b/docs/user/loaders/subversion.rst
similarity index 100%
rename from user/loaders/subversion.rst
rename to docs/user/loaders/subversion.rst
diff --git a/user/logos/arch.png b/docs/user/logos/arch.png
similarity index 100%
rename from user/logos/arch.png
rename to docs/user/logos/arch.png
diff --git a/user/logos/archive.png b/docs/user/logos/archive.png
similarity index 100%
rename from user/logos/archive.png
rename to docs/user/logos/archive.png
diff --git a/user/logos/aur.png b/docs/user/logos/aur.png
similarity index 100%
rename from user/logos/aur.png
rename to docs/user/logos/aur.png
diff --git a/user/logos/bazaar.png b/docs/user/logos/bazaar.png
similarity index 100%
rename from user/logos/bazaar.png
rename to docs/user/logos/bazaar.png
diff --git a/user/logos/bitbucket.png b/docs/user/logos/bitbucket.png
similarity index 100%
rename from user/logos/bitbucket.png
rename to docs/user/logos/bitbucket.png
diff --git a/user/logos/bower.png b/docs/user/logos/bower.png
similarity index 100%
rename from user/logos/bower.png
rename to docs/user/logos/bower.png
diff --git a/user/logos/cgit.png b/docs/user/logos/cgit.png
similarity index 100%
rename from user/logos/cgit.png
rename to docs/user/logos/cgit.png
diff --git a/user/logos/conda.png b/docs/user/logos/conda.png
similarity index 100%
rename from user/logos/conda.png
rename to docs/user/logos/conda.png
diff --git a/user/logos/cpan.png b/docs/user/logos/cpan.png
similarity index 100%
rename from user/logos/cpan.png
rename to docs/user/logos/cpan.png
diff --git a/user/logos/cran.png b/docs/user/logos/cran.png
similarity index 100%
rename from user/logos/cran.png
rename to docs/user/logos/cran.png
diff --git a/user/logos/crates.png b/docs/user/logos/crates.png
similarity index 100%
rename from user/logos/crates.png
rename to docs/user/logos/crates.png
diff --git a/user/logos/cvs.png b/docs/user/logos/cvs.png
similarity index 100%
rename from user/logos/cvs.png
rename to docs/user/logos/cvs.png
diff --git a/user/logos/debian.png b/docs/user/logos/debian.png
similarity index 100%
rename from user/logos/debian.png
rename to docs/user/logos/debian.png
diff --git a/user/logos/deposit.png b/docs/user/logos/deposit.png
similarity index 100%
rename from user/logos/deposit.png
rename to docs/user/logos/deposit.png
diff --git a/user/logos/git.png b/docs/user/logos/git.png
similarity index 100%
rename from user/logos/git.png
rename to docs/user/logos/git.png
diff --git a/user/logos/gitea.png b/docs/user/logos/gitea.png
similarity index 100%
rename from user/logos/gitea.png
rename to docs/user/logos/gitea.png
diff --git a/user/logos/github.png b/docs/user/logos/github.png
similarity index 100%
rename from user/logos/github.png
rename to docs/user/logos/github.png
diff --git a/user/logos/gitlab.png b/docs/user/logos/gitlab.png
similarity index 100%
rename from user/logos/gitlab.png
rename to docs/user/logos/gitlab.png
diff --git a/user/logos/gnu.png b/docs/user/logos/gnu.png
similarity index 100%
rename from user/logos/gnu.png
rename to docs/user/logos/gnu.png
diff --git a/user/logos/gogs.png b/docs/user/logos/gogs.png
similarity index 100%
rename from user/logos/gogs.png
rename to docs/user/logos/gogs.png
diff --git a/user/logos/golang.png b/docs/user/logos/golang.png
similarity index 100%
rename from user/logos/golang.png
rename to docs/user/logos/golang.png
diff --git a/user/logos/hackage.png b/docs/user/logos/hackage.png
similarity index 100%
rename from user/logos/hackage.png
rename to docs/user/logos/hackage.png
diff --git a/user/logos/launchpad.png b/docs/user/logos/launchpad.png
similarity index 100%
rename from user/logos/launchpad.png
rename to docs/user/logos/launchpad.png
diff --git a/user/logos/maven.png b/docs/user/logos/maven.png
similarity index 100%
rename from user/logos/maven.png
rename to docs/user/logos/maven.png
diff --git a/user/logos/mercurial.png b/docs/user/logos/mercurial.png
similarity index 100%
rename from user/logos/mercurial.png
rename to docs/user/logos/mercurial.png
diff --git a/user/logos/nixguix.png b/docs/user/logos/nixguix.png
similarity index 100%
rename from user/logos/nixguix.png
rename to docs/user/logos/nixguix.png
diff --git a/user/logos/npm.png b/docs/user/logos/npm.png
similarity index 100%
rename from user/logos/npm.png
rename to docs/user/logos/npm.png
diff --git a/user/logos/opam.png b/docs/user/logos/opam.png
similarity index 100%
rename from user/logos/opam.png
rename to docs/user/logos/opam.png
diff --git a/user/logos/packagist.png b/docs/user/logos/packagist.png
similarity index 100%
rename from user/logos/packagist.png
rename to docs/user/logos/packagist.png
diff --git a/user/logos/phabricator.png b/docs/user/logos/phabricator.png
similarity index 100%
rename from user/logos/phabricator.png
rename to docs/user/logos/phabricator.png
diff --git a/user/logos/pubdev.png b/docs/user/logos/pubdev.png
similarity index 100%
rename from user/logos/pubdev.png
rename to docs/user/logos/pubdev.png
diff --git a/user/logos/puppet.png b/docs/user/logos/puppet.png
similarity index 100%
rename from user/logos/puppet.png
rename to docs/user/logos/puppet.png
diff --git a/user/logos/pypi.png b/docs/user/logos/pypi.png
similarity index 100%
rename from user/logos/pypi.png
rename to docs/user/logos/pypi.png
diff --git a/user/logos/rubygems.png b/docs/user/logos/rubygems.png
similarity index 100%
rename from user/logos/rubygems.png
rename to docs/user/logos/rubygems.png
diff --git a/user/logos/sourceforge.png b/docs/user/logos/sourceforge.png
similarity index 100%
rename from user/logos/sourceforge.png
rename to docs/user/logos/sourceforge.png
diff --git a/user/logos/subversion.png b/docs/user/logos/subversion.png
similarity index 100%
rename from user/logos/subversion.png
rename to docs/user/logos/subversion.png
diff --git a/user/logos/tuleap.png b/docs/user/logos/tuleap.png
similarity index 100%
rename from user/logos/tuleap.png
rename to docs/user/logos/tuleap.png
diff --git a/user/make.bat b/docs/user/make.bat
similarity index 100%
rename from user/make.bat
rename to docs/user/make.bat
diff --git a/user/save_code_now/webhooks/index.rst b/docs/user/save_code_now/webhooks/index.rst
similarity index 100%
rename from user/save_code_now/webhooks/index.rst
rename to docs/user/save_code_now/webhooks/index.rst
diff --git a/requirements-swh-dev.txt b/requirements-swh-dev.txt
index fe17c6fb..48cb1bb0 100644
--- a/requirements-swh-dev.txt
+++ b/requirements-swh-dev.txt
@@ -10,6 +10,7 @@
 ../swh-deposit[server]
 ../swh-fuse
 ../swh-graph[luigi]
+../swh-graphql
 ../swh-icinga-plugins
 ../swh-indexer
 ../swh-journal
diff --git a/requirements-swh.txt b/requirements-swh.txt
index 86380c48..c0474ce6 100644
--- a/requirements-swh.txt
+++ b/requirements-swh.txt
@@ -6,6 +6,7 @@ swh.dataset[luigi]
 swh.deposit[server]
 swh.fuse
 swh.graph[luigi]
+swh.graphql
 swh.indexer
 swh.journal
 swh.lister
diff --git a/swh/docs/sphinx/conf.py b/swh/docs/sphinx/conf.py
index b85f7118..d3961456 100755
--- a/swh/docs/sphinx/conf.py
+++ b/swh/docs/sphinx/conf.py
@@ -1,6 +1,7 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
+# Copyright (C) 2017-2022  The Software Heritage developers
+# See the AUTHORS file at the top-level directory of this distribution
+# License: GNU Affero General Public License version 3, or any later version
+# See top-level LICENSE file for more information
 
 import logging
 import os
@@ -11,7 +12,7 @@ from sphinx.ext import autodoc
 from swh.docs.django_settings import force_django_settings
 
 # General information about the project.
-project = "Software Heritage - Development Documentation"
+project = "Software Heritage - Documentation"
 copyright = "2015-2022  The Software Heritage developers"
 author = "The Software Heritage developers"
 
@@ -56,9 +57,14 @@ master_doc = "index"
 # A string of reStructuredText that will be included at the beginning of every
 # source file that is read.
 # A bit hackish but should work both for each swh package and the whole swh-doc
-rst_prolog = """
-.. include:: /../../swh-docs/docs/swh_substitutions
-"""
+if os.path.exists("../../docs/swh_substitutions"):
+    rst_prolog = """
+    .. include:: /../../docs/swh_substitutions
+    """
+elif os.path.exists("../../swh-docs/docs/swh_substitutions"):
+    rst_prolog = """
+    .. include:: /../../swh-docs/docs/swh_substitutions
+    """
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -81,9 +87,8 @@ language = "en"
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = [
     "_build",
-    "swh-icinga-plugins/index.rst",
-    "swh.loader.cvs.rcsparse.setup.rst",
-    "apidoc/swh.loader.cvs.rcsparse.setup.rst",
+    "**swh-icinga-plugins/index.rst",
+    "**swh.loader.cvs.rcsparse.setup.rst",
     "**/swh/lister/maven/README.md",
     "**/swh/loader/cvs/cvs2gitdump/README.md",
     "**/swh/web/tests/resources/contents/code/extensions/test.md",
@@ -202,10 +207,6 @@ swh_package_doc_tox_build = os.environ.get("SWH_PACKAGE_DOC_TOX_BUILD", False)
 # documentation with tox to remove warnings and suppress
 # those related to unresolved references
 if swh_package_doc_tox_build:
-    swh_substitutions = os.path.join(
-        os.path.dirname(__file__), "../../../docs/swh_substitutions"
-    )
-    rst_prolog = f".. include:: /{swh_substitutions}"
     suppress_warnings = ["ref.ref"]
     html_favicon = ""
     html_logo = ""
@@ -259,7 +260,7 @@ def set_django_settings(app, env, docname):
 def add_glossary_to_index(app, docname, source):
     if docname == "index":
         glossary_path = os.path.join(
-            os.path.dirname(__file__), "../../../docs/glossary.rst"
+            os.path.dirname(__file__), "../../../docs/devel/glossary.rst"
         )
         with open(glossary_path, "r") as glossary:
             source[0] += "\n" + glossary.read()
diff --git a/sysadm/_templates/layout.html b/sysadm/_templates/layout.html
deleted file mode 100644
index 1d3add34..00000000
--- a/sysadm/_templates/layout.html
+++ /dev/null
@@ -1,21 +0,0 @@
-{% extends "!layout.html" %}
-
-{# copied from sphinx_rtd_theme/layout.html, with the extra "Development Documentation" link #}
-{%- block menu %}
-  {%- set toctree = toctree(maxdepth=theme_navigation_depth|int,
-                            collapse=theme_collapse_navigation|tobool,
-                            includehidden=theme_includehidden|tobool,
-                            titles_only=theme_titles_only|tobool) %}
-  {%- if toctree %}
-    {{ toctree }}
-  {%- else %}
-    <!-- Local TOC -->
-    <div class="local-toc">{{ toc }}</div>
-  {%- endif %}
-
-  <hr />
-
-  <ul>
-      <li class="toctree-l1"><a href="/devel/">Development Documentation</a></li>
-  </ul>
-{%- endblock %}
diff --git a/tox.ini b/tox.ini
index acaafd18..b8ef4295 100644
--- a/tox.ini
+++ b/tox.ini
@@ -14,19 +14,16 @@ deps =
 setenv =
   SWHPKGDIR = {envsitepackagesdir}/swh
 commands =
-  {envpython} -m pifpaf run postgresql -- make -C sysadm {posargs:html}
-  {envpython} -m pifpaf run postgresql -- make -C user {posargs:html}
   {envpython} -m pifpaf run postgresql -- make -C docs {posargs:html}
 
 [testenv:sphinx-dev]
 allowlist_externals = make
+
 setenv =
   SWHPKGDIR = {envsitepackagesdir}/swh
 commands =
   # use custom install script for dev build
   make pip-install-swh-dev
-  {envpython} -m pifpaf run postgresql -- make -C sysadm {posargs:html}
-  {envpython} -m pifpaf run postgresql -- make -C user {posargs:html}
   {envpython} -m pifpaf run postgresql -- make -C docs {posargs:html}
 
 [testenv:black]
-- 
GitLab