vlorentz authored 2 years ago and vlorentz committed 2 years ago

The only two titles at the second level were 'Important documentation links'
and 'Content', which look weird and are not very useful.

And this level prevented headings inside package documentation from being
shown in the TOC at all, which means the TOC couldn't be used to navigate
within a package's documentation.

vlorentz authored 2 years ago and vlorentz committed 2 years ago

To match the level we had de facto before merging devel/sysadm/user
into a single tree

0e55968d removed :titlesonly: from the
root toctree, which caused sphinx_rtd_theme to switch the mode it uses
to display *all* sidebars.

This config change reverts this behavior, but keeps the content of
pages unchanged.

suggested by @douardda

It simplifies documentation build configuration as the include path
might change depending on where the sphinx-build command is invoked.

These changes allow to build all SWH documentations (developmment, system
administration and user) using a single sphinx-build command, meaning they
are now merged into a single one with shared index of references.

Development documentation is now rooted to docs/devel, user one to docs/user
and sysadmin one to docs/sysadm so a good amount of files were moved.

A couple of configuration files and makefiles were updated to reflect that change
and the building / cleaning processes were made more reliable.

Calling make in root directory of swh-docs will execute the development build
of the documentation in a tox environment while calling make in docs folder
will use the current virtualenv.

It remains possible to build each documentation in a standalone way by
calling make in their root directory.

Closes #4496

Ref. swh/infra/sysadm-environment#4724

Some deprecated tox 3.x features have been removed in tox 4.x
and some install behaviors changed between the two versions.

So add tox 4.x support while keeping tox >= 3.7 compatibility.

vlorentz authored 2 years ago and Antoine R. Dumont committed 2 years ago

It's no longer built for it.

Document new metrics on outgoing API requests

See merge request swh/devel/swh-docs!274

Document statsd metrics and link to dashboards

See merge request swh/devel/swh-docs!270

Related to T4717

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

Related to https://gitlab.softwareheritage.org/infra/sysadm-environment/-/issues/4675

Related to https://gitlab.softwareheritage.org/infra/sysadm-environment/-/issues/4674

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).

Thanks to douardda for noticing.

sphinx-design is an iteration on sphinx-panels and intends to replace
it. It offers more interesting web components like cards which we will
be happy to use for the landing page.

Migration tips are available at:
https://sphinx-design.readthedocs.io/en/rtd-theme/get_started.html#migrating-from-sphinx-panels

Since this got improved using an intermediary build-deps container.