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

they will remain for internal use only, so should not be mentioned in this
public spec

this reverts the documentation part of 67fade5f

related to T1330

used by the swh-docs to generate images and schemas when building the
whole documentation.

to prevent sphinx from complaining about these not being included.

double back-quote (``) are not interpreted when inside a emphasis block.

Promote "Resolution" to a new top-level section, because it's now rather
voluminous.

As part of this document the resolver limitations of identifiers.org, that get
in the way of PID contextual information.

Closes T1015
Closes T1223

it makes life a bit easier for CI (less dependencies).

Related D454

text adapted from iPRES 2017 paper about Software Heritage, section "Data
Model"

Closes T787

Closes T1041