diff --git a/docs/cli.rst b/docs/cli.rst --- a/docs/cli.rst +++ b/docs/cli.rst @@ -2,5 +2,5 @@ ====================== .. click:: swh.model.cli:identify - :prog: swh identify - :show-nested: + :prog: swh identify + :show-nested: diff --git a/docs/persistent-identifiers.rst b/docs/persistent-identifiers.rst --- a/docs/persistent-identifiers.rst +++ b/docs/persistent-identifiers.rst @@ -257,34 +257,30 @@ --------------------------- * The following `SWHID - `_ + `__ denotes the lines 9 to 15 of a file content that can be found at absolute path ``/Examples/SimpleFarm/simplefarm.ml`` from the root directory of the revision ``swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0`` that is contained in the snapshot ``swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9`` taken from the origin - ``https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git``: + ``https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git``:: -.. code-block:: url - - swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b; - origin=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git; - visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9; - anchor=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0; - path=/Examples/SimpleFarm/simplefarm.ml; - lines=9-15 + swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b; + origin=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git; + visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9; + anchor=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0; + path=/Examples/SimpleFarm/simplefarm.ml; + lines=9-15 * Here is an example of a `SWHID - `_ - with a file path that requires percent-escaping: - -.. code-block:: url - - swh:1:cnt:f10371aa7b8ccabca8479196d6cd640676fd4a04; - origin=https://github.com/web-platform-tests/wpt; - visit=swh:1:snp:b37d435721bbd450624165f334724e3585346499; - anchor=swh:1:rev:259d0612af038d14f2cd889a14a3adb6c9e96d96; - path=/html/semantics/document-metadata/the-meta-element/pragma-directives/attr-meta-http-equiv-refresh/support/x%3Burl=foo/ + `__ + with a file path that requires percent-escaping:: + + swh:1:cnt:f10371aa7b8ccabca8479196d6cd640676fd4a04; + origin=https://github.com/web-platform-tests/wpt; + visit=swh:1:snp:b37d435721bbd450624165f334724e3585346499; + anchor=swh:1:rev:259d0612af038d14f2cd889a14a3adb6c9e96d96; + path=/html/semantics/document-metadata/the-meta-element/pragma-directives/attr-meta-http-equiv-refresh/support/x%3Burl=foo/ Implementation diff --git a/swh/model/cli.py b/swh/model/cli.py --- a/swh/model/cli.py +++ b/swh/model/cli.py @@ -218,7 +218,7 @@ metavar="PATTERN", multiple=True, help="Exclude directories using glob patterns \ - (e.g., '*.git' to exclude all .git directories)", + (e.g., ``*.git`` to exclude all .git directories)", ) @click.option( "--verify", @@ -242,7 +242,7 @@ Tip: you can pass "-" to identify the content of standard input. \b - Examples: + Examples:: \b $ swh identify fork.c kmod.c sched/deadline.c diff --git a/swh/model/identifiers.py b/swh/model/identifiers.py --- a/swh/model/identifiers.py +++ b/swh/model/identifiers.py @@ -47,7 +47,7 @@ class ExtendedObjectType(enum.Enum): """Possible object types of an ExtendedSWHID. - The variants are a superset of :cls:`ObjectType`'s""" + The variants are a superset of :class:`ObjectType`'s""" SNAPSHOT = "snp" REVISION = "rev" @@ -729,24 +729,22 @@ A raw_extrinsic_metadata identifier is a salted sha1 (using the git hashing algorithm with the ``raw_extrinsic_metadata`` object type) of - a manifest following the format: - - ``` - target $ExtendedSwhid - discovery_date $Timestamp - authority $StrWithoutSpaces $IRI - fetcher $Str $Version - format $StrWithoutSpaces - origin $IRI <- optional - visit $IntInDecimal <- optional - snapshot $CoreSwhid <- optional - release $CoreSwhid <- optional - revision $CoreSwhid <- optional - path $Bytes <- optional - directory $CoreSwhid <- optional - - $MetadataBytes - ``` + a manifest following the format:: + + target $ExtendedSwhid + discovery_date $Timestamp + authority $StrWithoutSpaces $IRI + fetcher $Str $Version + format $StrWithoutSpaces + origin $IRI <- optional + visit $IntInDecimal <- optional + snapshot $CoreSwhid <- optional + release $CoreSwhid <- optional + revision $CoreSwhid <- optional + path $Bytes <- optional + directory $CoreSwhid <- optional + + $MetadataBytes $IRI must be RFC 3987 IRIs (so they may contain newlines, that are escaped as described below) @@ -769,7 +767,7 @@ ie. by adding a space after them. Returns: - str: the intrinsic identifier for `metadata` + str: the intrinsic identifier for ``metadata`` """ # equivalent to using math.floor(dt.timestamp()) to round down, diff --git a/swh/model/merkle.py b/swh/model/merkle.py --- a/swh/model/merkle.py +++ b/swh/model/merkle.py @@ -7,7 +7,7 @@ import abc from collections.abc import Mapping -from typing import Iterator, List, Set +from typing import Dict, Iterator, List, Set def deep_update(left, right): @@ -101,16 +101,18 @@ The collection of updated data from the tree is implemented through the :func:`collect` function and associated helpers. - Attributes: - data (dict): data associated to the current node - parents (list): known parents of the current node - collected (bool): whether the current node has been collected - """ __slots__ = ["parents", "data", "__hash", "collected"] - """Type of the current node (used as a classifier for :func:`collect`)""" + data: Dict + """data associated to the current node""" + + parents: List + """known parents of the current node""" + + collected: bool + """whether the current node has been collected""" def __init__(self, data=None): super().__init__()