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

This is the inventory we need in order to resolve swh/meta#4931

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.

Antoine Lambert authored 2 years ago and Antoine Lambert committed 1 year ago

It was excluded a couple of years ago as no relevant Python code was
contained in that package but this is no longer the case.

Those URLs makes the ShortenLinkTransform sphinx post-transform from the
pydata theme raise an exception when it attempts to process them using
Python >= 3.11.4, see https://github.com/python/cpython/issues/103848.

So align with other service URLs containing brackets in that doc page
and remove their scheme.

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

Paul Wise authored 1 year ago and Jérémy Bobbio (Lunar) committed 1 year ago

Asked-in: https://archive.softwareheritage.org/admin/add-forge/request/200/

Sadly there is a bug in the parsing of quotes in the `console` lexer.
So revert to `shell` which works fine and remove the prompt.

Also replace some tabs by spaces.

Co-Authored-By: Benoit Chauvet <contact@benoitchauvet.com>
Fixes: swh/devel/swh-docs#4745

This allows the generated snippet (by pygnents) to better handle the
selection for copy/pasting. Namely, the prompt will not be selected
which is what is expected for this kind of example snip.

- adapt command line examples to match current state od the swh-docker
  repository,
- add details about node label assignments,
- give details about replication factors for replayer services.

To generate the svg out of the mermaid source code:
```
$ docker run --rm -u `id -u`:`id -g` -v $(pwd):/data \
  minlag/mermaid-cli -i alertmanager-irc-relay.mmd
```

Refs. swh/infra/sysadm-environment#4525

This is not only used by the scheduler, and referencing the full range
of upstream settings may be useful.

Related to swh/infra/sysadm-environment#4824

Related to swh/infra/sysadm-environment#5024

Related to swh/infra/sysadm-environment#4998

Related to swh/infra/sysadm-environment#4824

Related to swh/infra/sysadm-environment#4824

Related to swh/infra/sysadm-environment#4824

Related to swh/meta#5043.

So CLI documentation can link to it instead of repeating the whole
configuration of each block.

This document Software Heritage policy regarding how takedown notices
must be handled on mirrors. Currently we are missing tooling to
implement it in full, but we can still document the stopgap process
and what we are aiming.

Thanks to ardumont and vlorentz for proofreading and spotting several
typos, syntax and grammar issues.

Ref swh/meta#4975