add build logic to generate unified development documentation

README.md

+swh-docs
+========
+
+This module contains (the logics for generating) the Software Heritage
+development documentation.
+
+Specifically, it contains some general information about Software Heritage
+internals (stuff that would not fit in any other specific software component of
+the Software Heritage stack) and bundle them together component-specific
+documentation coming from other modules of the stack.
+
+All documentation is written and typeset using [Sphinx][1]. General
+documentation is shipped as part of this module. Module-specific documentation
+is centralized here via symlinks to the `docs/` dirs of individual modules.
+Therefore to build the full documentation you need a working and
+complete [Software Heritage development environment][2].
+
+[1]: http://www.sphinx-doc.org/
+[2]: https://forge.softwareheritage.org/source/swh-environment/
+
+
+How to build the doc
+--------------------
+
+    $ cd docs
+	$ make html
+
+Behind the scene, this will do two things:
+
+### 1. Generate sphinx-apidoc rst documents for all modules
+
+    $ cd swh-environment
+	$ make docs-apidoc
+
+This will *not* build the documentation in each module (there is `make docs`
+for that), but will use `sphinx-apidoc` to generate documentation indexes for
+each (sub)modules in the various Software Heritage components.
+
+As `sphinx-apidoc` refuses to overwrite old documents, before proceeding you
+might need to clean up old cruft with:
+
+    $ cd swh-environment
+    $ make docs-clean
+
+
+### 2. Build the documentation
+
+    $ cd swh-docs/docs
+    $ make html
+
+The HTML documentation is now available starting from `_build/html/index.html`.
+
+
+Cleaning up
+-----------
+
+    $ cd docs
+    $ make clean
+    $ make distclean
+
+The former (`make clean`) will only clean the local Sphinx build, without
+touching other modules. The latter (`make distclean`) will also clean Sphinx
+builds in all other modules.

docs/.gitignore

+*-stamp
 _build/
+swh-*

docs/Makefile

-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXPROJ    =
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+html: sphinx/html
+sphinx/html: links-stamp apidoc-stamp
+
+links-stamp:
+	bin/ln-sphinx-subprojects
+	touch $@
+
+apidoc-stamp:
+	make -C ../../ docs-apidoc
+	touch $@
+
+clean: sphinx/clean
+	bin/ln-sphinx-subprojects --remove
+	rm -f *-stamp
+
+distclean: clean
+	make -C ../../ docs-clean
+
+help: sphinx/help
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
-.PHONY: help Makefile
+sphinx/%:
+	@$(SPHINXBUILD) -M $* "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
-# 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)
+.PHONY: html help clean

docs/bin/ln-sphinx-subprojects

+#!/bin/bash
+set -e
+
+create_links () {
+    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
+    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
+}
+
+if [ "$1" = "--remove" ] ; then
+    remove_links
+else
+    create_links
+fi