vlorentz authored 1 year ago and vlorentz committed 1 year ago

This reverts commit ae901af0.

Two people within the team reported it's hard to read for them
with the new theme (color-blindness)

- use #E20026 as primary (SWH's red)
- use secondary color for main's page buttons
- use #52566D (light) / #DBDBDB (dark) secondary color

This is implements the landing page that was designed during the
documentation sprint in November 2022.

There is probably further work to be done on the copy, maybe tweak
colors and margins on the cards. Proper support for dark mode would
be nice as well. It’s a bit ugly for now.

The images are coming from <https://undraw.co/>. The license does not
require attribution. Full license text reads as follow:

    Copyright 2022 Katerina Limpitsouni

    All images, assets and vectors published on unDraw can be used for
    free. You can use them for noncommercial and commercial purposes.
    You do not need to ask permission from or provide credit to the
    creator or unDraw.

    More precisely, unDraw grants you an nonexclusive, worldwide
    copyright license to download, copy, modify, distribute, perform,
    and use the assets provided from unDraw for free, including for
    commercial purposes, without permission from or attributing the
    creator or unDraw.  This license does not include the right to
    compile assets, vectors or images from unDraw to replicate a similar
    or competing service, in any form or distribute the assets in packs
    or otherwise. This extends to automated and non-automated ways to
    link, embed, scrape, search or download the assets included on the
    website without our consent.

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.

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