Refactor the sphinx-dev build environment to get rid of the link-stamp step

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

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

docs/Makefile

@@ -3,7 +3,7 @@ SPHINXBUILD = sphinx-build
 SOURCEDIR = .
 BUILDDIR = _build
 HTMLDIR = $(BUILDDIR)/html
-SWHPKGDIR = sources/swh/
+SWHPKGDIR ?= sources/swh/
 
 INSTALL_HOST = pergamon.internal.softwareheritage.org
 INSTALL_DIR = /srv/softwareheritage/docs/webroot/devel
@@ -21,14 +21,10 @@ APIDOC_SWH_EXCLUDES = $(patsubst %,$(SWHPKGDIR)/%,$(APIDOC_EXCLUDES))
 
 html: sphinx/html
 
-sphinx/html: links-stamp apidoc-stamp images-stamp rec-build-stamp
-
-links-stamp:
-	bin/ln-sphinx-subprojects
-	touch $@
+sphinx/html: apidoc-stamp images-stamp rec-build-stamp
 
 apidoc: apidoc-stamp
-apidoc-stamp: links-stamp images-stamp
+apidoc-stamp: images-stamp
 	$(SPHINXAPIDOC) --implicit-namespaces $(APIDOC_OPTS) -o $(APIDOC_DIR) $(SWHPKGDIR) $(APIDOC_SWH_EXCLUDES)
 	touch $@
 
@@ -44,7 +40,6 @@ rec-build-stamp: $(wildcard ../../swh-*/docs/*.rst)
 	touch $@
 
 clean: sphinx/clean
-	bin/ln-sphinx-subprojects --remove
 	$(MAKE) -C images clean
 	rm -f *-stamp
 	rm -f $(APIDOC_DIR)/*

docs/bin/ln-sphinx-subprojects

-#!/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
-            rsync -a --include='*.py' --include='*/' --exclude='*' --prune-empty-dirs "../../${pymodule}/swh" "sources/"
-        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
-}
-
-if [ "$1" = "--remove" ] ; then
-    remove_links
-else
-    create_links
-fi

requirements-swh-dev.txt

 # Add here internal Software Heritage dependencies, one per line.
 # Dependencies need to be ordered in a way that ensure only
 # development versions will be used (not the release ones hosted on PyPI).
--e ../swh-core[http,db,logging]
--e ../swh-model
--e ../swh-objstorage[testing]
--e ../swh-storage[schemata]
--e ../swh-journal
--e ../swh-scheduler
--e ../swh-deposit
--e ../swh-graph
--e ../swh-icinga-plugins
--e ../swh-indexer
--e ../swh-lister
--e ../swh-loader-core
--e ../swh-loader-git
--e ../swh-loader-mercurial
--e ../swh-loader-svn
--e ../swh-search
--e ../swh-vault
--e ../swh-web
--e ../swh-web-client
--e ../swh-scanner
+../swh-core[http,db,logging]
+../swh-model
+../swh-journal
+../swh-objstorage[testing]
+../swh-storage[schemata]
+../swh-scheduler
+../swh-deposit
+../swh-graph
+../swh-icinga-plugins
+../swh-indexer
+../swh-lister
+../swh-loader-core
+../swh-loader-git
+../swh-loader-mercurial
+../swh-loader-svn
+../swh-search
+../swh-vault
+../swh-web
+../swh-web-client
+../swh-scanner

tox.ini

@@ -9,14 +9,16 @@ passenv = SPHINXOPTS JAVA_HOME
 extras =
   building
 deps =
-  django < 2
+  django < 3
   pifpaf
 commands =
   {envpython} -m pifpaf run postgresql -- make -C docs {posargs:html}
 
 [testenv:sphinx-dev]
+setenv =
+  SWHPKGDIR = {envsitepackagesdir}/swh
 deps =
-  django < 2
+  django < 3
   -rrequirements-swh-dev.txt
   pifpaf
 commands =