When building package documentation outside tox by calling make in the
docs directory, the include of Makefile.sphinx inside the docs Makefile
was failing as its relative path was invalid.

So adapt this relative path according if the SWH_PACKAGE_DOC_TOX_BUILD
environment variable is set or not.

Convert README from markdown to ReST to make it embeddable in
docs/index.rst

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

There were two issues that was preventing to browse some SWHIDs given as
examples in that documentation:

- Some sphinx links were broken in rDMODe1c3fe80731226618616117dfd67a95f3d365645

- A SWHID with ';' in its path qualifier was correctly percent escaped but
  when used as URL argument an extra percent escaping is required as HTTP
  server will unescape URL arguments and thus break SWHID percent escaping.

Closes T4721

This changes the deprecated :show-nested: instruction to the :nested: one [1].
This also fixes warning about misdefined block [2]

[1] https://sphinx-click.readthedocs.io/en/latest/usage/#directive-click

[2]
```
10:38:38  Warning, treated as error:
10:38:38  /var/lib/jenkins/workspace/DMOD/tests-on-diff/docs/cli.rst:14:Literal block expected; none found.
10:38:38  make: *** [../../swh-docs/Makefile.sphinx:32: sphinx/html] Error 2
10:38:38  make: Leaving directory '/var/lib/jenkins/workspace/DMOD/tests-on-diff/docs'
10:38:38  ERROR: InvocationError for command '/usr/bin/make -I ../.tox/sphinx/src/swh-docs/swh/ -C docs' (exited with code 2)
```

Sphinx >=4.4.0 raises warnings (which are errors for us) when using
warnings instead of an extlink role defined in the configuration

swh-deposit needs to link to some of them.

We don't store those

Revision and release do not generally allow 'arbitrary' metadata;
and it was missing ExtIDs and REMD

Otherwise, they will get an error asking them to install Click
(or Dulwich if Click installed and they use -t snapshot)

 - Use dia directly to convert from .dia to .svg (inkscape would use dia via a
 plugin anyway)
 - Add proper runes to detect inkscape >= 1 and use the export options for that.

When Software Heritage persistent identifiers were introduced, they were not
yet abbreviated as SWHIDs.

Now that abbreviation is growing adoption, rename some functions and types in
swh.model.identifiers for consistency:

  - PersistentId -> SWHID

  - persistent_identifier -> swhid

  - parse_persistent_identifier -> parse_swhid

Backward compatibility with previous naming is maintained but deprecation
warnings are introduced to encourage the use of the new names.

Numerous variables in swh.model codebase have also been renamed accordingly.

Also rework and improve documentation.

Stefano Zacchiroli authored 4 years ago and Roberto Di Cosmo committed 4 years ago

Reviewers: rdicosmo

Reviewed By: rdicosmo

Differential Revision: https://forge.softwareheritage.org/D3108

Closes T1003

 - merge grammars into a single one
 - explain better that SWHIDs are made up of core identifier + qualifiers
 - separate qualifier into context and fragment onex
 - add reference to swh-identify

Closes T2379

hat tip to @rdicosmo for noticing

Hinting at the origin_visit_update model

Related to T2310