Suggested by @zack: “it's useful to have it on top (because a lot people
use docs.s.o for that, at least now), but it also belongs to devel doc,
so people will look for it on the left as well”

After merging various parts of Software Heritage documentation in a
single Sphinx instance, the navigation using the Read The Docs theme
became seriously cumbersome.

We switch to PyData Sphinx theme: a clean, Bootstrap-based Sphinx theme
by and for the PyData community. For details, please refer to:
https://pydata-sphinx-theme.readthedocs.io/

One major upside is that by default supports three level of navigation:

- top-level parts in the header bar (for us, they would refer to
  `devel`, `sysadm` and `user`)
- a left sidebar for sections in the current part,
- a right sidebar for the contents of the current page.

This maps really well to our hierarchy.

Some changes made to better navigate the various parts of our
navigation:

- Rename “Development Documentation” to just “Development”.
- Rename “Sysadmin Documentation” to just “Infrastructure”.
- Rename “User Documentation” to just “Usage”.
- Promote the API reference from Development to the top-level.

Some other improvements to better benefit the new theme:

- Replace the vertical logo with the horizontal one to better fit the
  header.
- Add links to GitLab, PyPI and status.s.o to the header.
- Remove the unused Alegreya font.

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.

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

This nests the historical roadmap under a specific roadmap/index
toctree, so that they don't all show up in the sidebar.

This fixes the build [1]

[1] https://jenkins.softwareheritage.org/job/DDOC/job/dev/1139/console

Without this, the actual documentation build will fail once a new package is
incompletely installed.

and merge duplicate parts

Related to T3829

This has been broken [1] for a while.

[1] https://jenkins.softwareheritage.org/view/swh-draft/job/DDOC/job/dev/311/

Related to T3780

Closes T3737

As the toctree for the faq was included multiple times in index file,
the associated menu entry in the sidebar was not properly rendered.

In order to workaround the issue, ensure faq toctree is included once
in the index file and add reference to faq page in Getting started
top level section.

Also as faq subsection entries are no longer included in the sidebar
menu, display a local toctree at the top of the faq page.

Closes T3657

This also cleans up rendering and whitespace issues.

Related to T3154

The following document demonstrates how to create a new swh package in the current swh
phabricator instance and reference it so the Continuous Integration (CI) is able to
build the new module.

Related to T3179

So it's integrated in the build.

Related to T2845

The FAQ was put in a single file in faq/faq.rst as a hack, using
multiple top-level headers in the same file to make them appear
in the global TOC.

With this change, the TOC is moved to the index.rst file, with
a single top-level header, and uses a local TOC instead, as it
should be.

Additionally, this removed the manually-written TOC in the main
index to use an auto-generated one.

This opens the developers faq we short-listed during the documentation sprint. Question
are regrouped under a specific category.

Categories are listed from the main page and from the left menu.

Related to T3119

Related to T3119

initiate an infrastructure section and a network sub-section

Remark: the png of the plantuml diagram is committed because
the svg in not correctly rendered

Related to T3203

As it was, it was unclear that it linked to the documentation of internal
Python module, instead of the public HTTP API.

It used to only document the core components.

This commit does the following:

* expands the existing descriptions
* reorders them in didactical order
* and all the other components in two new tiers ("major" and "extra", in
  addition to "core")

I think it's a little clearer this way what Keycloak is
and when a reader should care (or not) about it.

To match the toctree.

I'm leaving keycloak out of it, because it does not actually describe
the architecture. It's only in the architecture toctree for lack of
a better place for now.

So the docker documentation is available on docs.softwareheritage.org instead
of linking to the source on Phabricator

This adds the roadmap entry in the site in the:
- index menu on the left (prior to the components listing)
- main page under a ` Roadmap` section just before the components section

Related to T3208