Update the README file for latest (normally tox-based) build system

README.md

@@ -15,46 +15,57 @@ 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
 --------------------
 
+Install the [Software Heritage development environment][2]
+
+    $ git clone https://forge.softwareheritage.org/source/swh-environment
+	$ cd swh-environment
+	$ ./bin/update  # this will clone needed git repos, inc. swh-doc
+	$ cd swh-doc
+
 Ensure you have the required tools to generate images ([graphviz][3]'s `dot`
 and [plantuml][4]). On a Debian system:
 
     $ sudo apt install plantuml graphviz
 
-[3]: https://graphviz.org
-[4]: http://plantuml.com
 
+It is also recomanded to build the doc using [tox][5], so ensure you have it
+installed, eg. on a Debian system:
 
-Then
+    $ sudo apt install tox
 
-    $ cd docs
-	$ make html
 
-Behind the scene, this will do two things:
+Then (from the `swh-environment/swh-doc/` directory):
+
+    $ tox -e sphinx-dev
+
+This tox environment will build the documentation from the sources available in
+the parent directory (`swh-environment`).
+
+Behind the scene, this tox environment will run the sphinx documentation
+building process via [pifpaf][6] to encapsulate the need os Postgresql to
+generate database schemas. The documentation building process itself consists
+mainly in 3 steps:
 
-### 1. Generate sphinx-apidoc rst documents for all modules
+### 1. Generate documentation assets for all modules
 
     $ cd swh-environment
-	$ make docs-apidoc
+	$ make docs-assets
 
 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.
+for that).
 
-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 api docs for all swh python packages
 
+    $ cd swh-docs/docs
+    $ make apidoc
 
-### 2. Build the documentation
+### 3. Build the documentation
 
     $ cd swh-docs/docs
     $ make
@@ -76,11 +87,13 @@ builds in all other modules.
 Publishing the doc
 ------------------
 
-    $ cd docs
-    $ make install
-    $ xdg-open https://docs.softwareheritage.org/devel/
+The publication of the documentation is now managed by the [CI][7].
+
+
 
-For the above to work you need to have ssh access into the machine
-hosting <https://docs.softwareheritage.org> (currently `pergamon`), and write
-access do the document root directory of that virtual host (currently granted
-to all members of the `swhdev` UNIX group on Software Heritage machines).
+[1]: http://www.sphinx-doc.org/
+[2]: https://forge.softwareheritage.org/source/swh-environment/
+[3]: https://graphviz.org
+[4]: http://plantuml.com
+[5]: https://tox.readthedocs.io/
+[6]: https://github.com/jd/pifpaf