vlorentz authored 1 year ago and vlorentz committed 1 year ago

It was deprecated years ago, and no client used it in staging or prod
since 2022-04-11

GitLab will display the content of the README file when browsing the
repository. But in case the file is a symlink, it will display the
path pointed by the symlink. There is a 6 year old issue about this:
https://gitlab.com/gitlab-org/gitlab/-/issues/15093

We can workaround the issue by having the content at the root of the
repository and a symlink to this file in the `docs/` directory.

Tested in swh/devel/swh-py-template!27

In order to remove warnings about /apidoc/*.rst files being included
multiple times in toc when building full swh documentation, prefer to
include module indices only when building standalone package documentation.

Also include them the proper sphinx way.

Related to T4496

Setting the next_path query parameter is not required here as webapp login
view redirects by default to the homepage.

Related to T4399

It was always meant to be the latter, and it's also the only one that was implemented
in a release (as https://forge.softwareheritage.org/D7212 fixed the typo in the code
before it was released)

It was never actually tested...

This will be useful for metadata-only deposit, as there is not necessarily
and origin in the referenced SWHID; and even when there is, it is usually
not the actual source of the metadata.

Therefore, we need this new field to link back to the provenance of the metadata.

This fixes the build [1] [2]

[1]
```
10:49:23  Warning, treated as error:
10:49:23  /var/lib/jenkins/workspace/DDEP/tests-on-diff/docs/README.rst:40:hardcoded link 'https://archive.softwareheritage.org/save/' could be replaced by an extlink (try using ':swh_web:`save/`' instead)
```

[2] https://jenkins.softwareheritage.org/view/swh-draft/job/DDEP/job/tests/1741/console

It shouldn't be used anymore

They were only documented in the protocol reference/specification

The three update types are already too easy too confuse,
let's not add more confusing by documenting them in the
same subsections.

A reminder never hurts.

Also fixes the image path.

Everything was in 'Schema representation'...

It has nothing to do with swh-storage.

The terminology also implies it's somehow 'smart', but it only refers
to the database. (or to the deposit server itself in authentication.rst)

This only includes redirects for user documentation;
external links to the developer documentation would be broken,
but I don't think there are any such link and I don't want to
clutter the file tree unnecessarily.

This moves files around, so it will cause stale or broken links.
A future commit in swh-docs will set up redirects so the old URLs
still point to up-to-date documents.

It was written long ago, but wasn't discoverable so far.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections