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

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.

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.

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

Thanks to douardda for noticing.

sphinx-design is an iteration on sphinx-panels and intends to replace
it. It offers more interesting web components like cards which we will
be happy to use for the landing page.

Migration tips are available at:
https://sphinx-design.readthedocs.io/en/rtd-theme/get_started.html#migrating-from-sphinx-panels

It can be convenient to run the global swh documentation in the
current venv instead of using tox (notably to save time by skipping
dependencies installation).

It looks like the Makefile in docs folder was not really maintained
regarding that kind of documentation build so fix it in order to
restore local build.

Add landing page of loaders high-level documentation displaying
available ones in a table with the following column:

  - logo and name of the loader linking to its specific documentation

  - related links: source code, developer doc, development activity

  - current status: production, staging or development

  - link to related grant if any

Create one rst file per loader to further document.

Related to T3117

It is a common practice to open an external link in a new browser
tab so process external links with javascript when a documentation
page got loaded to enforce such behavior.

Corresponding RST document has been renamed to uri-scheme-swhids.rst
so add a redirection for URL backward compatibility.

with infrastructure sizing estimations.

This has been broken [1] for a while.

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

Related to T3780

This also:
- installs redirection from old location to the new one.
- install the intended audience on respective documentations.

Related to T3154

This also:
- installs redirection from old location to the new one.
- install the intended audience on respective documentations.

Related to T3154

The encountered issues have been fixed in release 1.8.0 of
sphinxcontrib-httpdomain.

That creates warning as well thus failing the build.

Related to T3648

This also adds a redirection from the old path "users" to the new one "user".

Related to T3650

Related to T3648

Related to T3648

Related to T3648

Related to T3648

This is the last part of the broken build [1].

To add back to the building part when ready.

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

Related to T3648

For now as the development only started recently. It's expected to be activated back
when ready.

Part of the broken build [1]

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

Related to T3648

On Jenkins, Phabricator repository callsign is used as source directory
instead of the short name.

There is no reason to filter out these warnings only in tox builds
as the issue comes from upstream httpdomain not in sync with latest
sphinx API.

It also enables to unstuck swh-web and swh-docs builds on Jenkins.