There are plenty of other phabricator links in another places in the
doc, but this ones are the first encountered by a new comer.

Related to swh/devel/swh-docs#4732

It needs to be set to the same color as the button in the card,
otherwise the hover color looks out of place.

The `swh-docs` building process symlinks the documentation for
individual modules into the `swh-docs` tree to generate a single Sphinx
project. The “Edit this page” link therefore needs to point to the right
repository on GitLab in these case.

We try to implement this using the `edit_page_url_template` option
of the PyData theme, see: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html#custom-edit-url

We can take advantage that it’s a Jinja2 template to recognize
that API documentation file path starts with `devel/swh-` and adjust
accordingly. This is a bit of a hack, but we can hope it’ll be enough as
long as we stay consistent.

- Closes: swh/devel/swh-docs#4735

This fixes python 3.7 support due to poetry, a dependency of isort, that
removed support for that Python version in a recent release.

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”

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.

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.