This is now partly done thanks to the following ingredients:

• the new swh-docs module, that contains
  1. a swh.docs python module that export a common Sphinx configuration that all our modules can use, possibly overriding it on a local basis
  2. logics for fetching Sphinx documents from all other Python modules and generating a single (html, or other) documentation bundle
• a skeleton in swh-py-template of a docs/ dir, that allows modules to generate their own piece of documentation, independently from the single big documentation bundle
  • the skeleton has been applied and committed in all our modules
  • the skeleton uses behind the scenes sphinx-apidoc to generate the .rst documents that correspond to our exported python modules
  • additional, module-specific documentation can be locally added in each module, following the usual Sphinx conventions, only the "apidoc" subdir is autogenerated

What is missing is… fixing all Sphinx errors that our docstrings, which up to now were absolutely not tested :-), spit out.