Source to redirect must be a docname and redirect link must be relative
to the redirected document.

This also reverts commit dbc52f9d as
those files are no longer needed.

vlorentz authored 2 months ago and vlorentz committed 2 months ago

To follow the package rename

so that we can add mermaid graphs in the documentation easily.

It fixes some warnings when building the SWH documentation.

Sphinx prints warnings when an extension does not declare it is safe to use
with parallel build and switch back to sequential build in that case.

Previously only parallel read warnings were filtered out so ensure parallel
write ones are also considered.

Distribute these Makefiles in share/swh-docs and move the
glossary.rst in share/swh-docs/docs/devel to keep the directory hierarchy
of the source repo.

Distribute this docs/devel/glossary.rst file as package data in
share/swh-docs since it is needed for locally building the doc
from swh packages.

Adapt the add_glossary_to_index sphinx hook to look for this file in
share/swh-docs in addition to the current relative path (which only
works if swh-docs in installed in editable with proper pip
config-settings and who knows what else). For local/editable installed
swh-docs, look a bit more than previously to attempt to catch the case
of editable_mode=strict pip config

The idea is to generalize the fact that all the swh packages should have
a README file in the root directory, but this should be included in the
sphinx documentation, for which the simplest way is to make the file
symlinked in docs/. For several reasons, it's simpler to make this
symlink creation handled by a hook/automation script at doc build time
rather than add the symlink in the git repo of the swh package.

Some extensions we are using does not declare them as safe for parallel read
so sphinx emits warnings when parallel build is used.

Filter out these warnings to fix CI builds.

It should fix doc CI builds as parallel build was recently enabled in jobs.

Latest pydata-sphinx-theme release prints a new warning about
an accessibility issue and recommends to set to False the
navigation_with_keys theme option.

It fixes CI jobs on Jenkins as sphinx warnings are treated as
errors.

See https://github.com/pydata/pydata-sphinx-theme/issues/1492

sphinx-carousel is a Sphinx extension for creating slideshows using
Bootstrap carousels. The extension supports the PyData Sphinx theme that
we are currently using.

This would be a nice addition to show the various steps of an algorithm
in swh-alter documentation.

See: https://sphinx-carousel.readthedocs.io/ and
https://getbootstrap.com/docs/5.1/components/carousel/

vlorentz authored 1 year ago and vlorentz committed 1 year ago

Logos were found anyway, somehow...

vlorentz authored 1 year ago and vlorentz committed 1 year ago

They turn out to have their own usefulness, in addition to the unified
'Software Origin' list:
swh/devel/swh-docs!355 (comment 137637)

and split line to make flake8 happy

swh-webhooks package is detected as swh-web by the code of that function
but django is not installed when building standalone doc for this package.

Logos in the table listing the forges were taking too much space,
resulting in unfortunate line breaks in other columns. Let’s reduce
their width to a minimum instead.

Also remove the secondary sidebar to get some extra space.

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

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

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

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.

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