As we have switched from Phabricator to GitLab, we now point at GitLab
documentation on how to automatically link and close issues from
commit messages.

Improvements on the section about commit messages are thrown in for good
measure.

Related to #4732

It was a bit outdated regarding the network range.

Refs. swh/infra/sysadm-environment#4772

Jérémy Bobbio (Lunar) authored 2 years ago and Jérémy Bobbio (Lunar) committed 2 years ago

See: https://tox.wiki/en/latest/upgrading.html#updating-usage-with-e

Related to swh/meta#4960

When building the full swh documentation, add a sphinx transform step
to include a swh package apidoc in the toc of its documentation index
page.

Fix #4736

It is no longer included in the doc toc.

Remove the reference to phabricator

Only a couple of. There are plenty others to go around, some of which are getting worked
on in parallel.

Refs. swh/devel/swh-docs#4732

The project homepage has a proeminent link to the documentation in its
header. Let’s have the documentation link back to the homepage then.

They were broken during the merge done in 0e55968d.

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.