Antoine Lambert authored 2 years ago and Antoine Lambert committed 1 year ago

It was excluded a couple of years ago as no relevant Python code was
contained in that package but this is no longer the case.

Add the standalone_package_doc sphinx tag when building standalone
documentation of a swh package.

It enables to conditionnally include content in package documentation,
like indices and tables for instance.

Related to T4496

Django settings modules were no longer filtered out from apidoc
processing when building standalone swh package documentation.

Regression introduced in 2f5cbf0c as tox files use SPHINXOPTS environment
variable to add custom sphinx options (like -W).

Previously the file patterns that sphinx-apidoc must exclude, stored
in the APIDOC_EXCLUDES variables, were expanded by the shell before
executing the tool resulting in a really long list of files to exclude.
Each time a file was processed by sphinx-apidoc, its path was compared
against that long list of files which was significantly slowing down
the apidoc generation process.

So ensure file exclude patterns are quoted to avoid shell expansion
and greatly speedup sphinx-apidoc execution.

Such files are not of interest for API documentation and can generate doc
build errors.

Since swh-web tests reorganization, we now have such file so we need to
exclude it from apidoc processing.

Sphinx started to crash recently because of that not needed file
processed by apidoc.

Previous values did not prevent sphinx-apidoc to walk the content
of these directories resulting in really long processing when
directories contain a lof of entries (node_modules for instance).

Now that sphinxcontrib-images extension has gained support for Sphinx > 2
in its 0.9.1 release, we can remove the restriction on Sphinx version in
the requirements file.

Also considering that we now rely on a virtualenv to build the doc, remove
the hacks to invocate sphinx-build and sphinx-apidoc in Makefiles.

Related to T2264

As a visible change of this, --separate is now also used on the main docs.s.o
build. That's desirable as it makes more navigable table of contents, with a
clearly visible hierarchy of submodules---which before this change were only
visible by scrolling the entire page.

so we do not build each swh-* twice with unavaoidable sphinx wrnings when
building each repo locally.

Rather than one big page for each top-level module, containing the apidoc of
all submodules.

This commit slighly modifies Makefiles in order to be able to build
the documentation on Debian stretch (using sphinx 1.4.9) but also
with the latest sphinx version to date (1.7.5).

Changes notably includes:

  - remove the --implicit-namespaces option for sphinx-apidoc as:

     * it is not needed
     * it is not supported on sphinx 1.4.9
     * output is not correct with sphinx 1.7.5

  - use sphinx -b option instead of -M for building html doc
    as an exception is raised otherwise when using sphinx 1.4.9

This is needed because the multiplexer makefile that build apidoc in all
modules explicitly call "make apidoc". Also, it is reasonable to do nothing
anyhow in that case if SKIP_APIDOC=yes is explicitly set.

Makefile.sphinx: also exclude root tests module for apidoc as it may have content defined in its __init__.py (like in swh-web for instance)

This allows you to still have python-sphinx and python3-sphinx coinstalled and
still build with Python 3.

use case: swh-storage