From 8d0352c181e93ce152429827588bd037f850d8f0 Mon Sep 17 00:00:00 2001
From: Valentin Lorentz <vlorentz@softwareheritage.org>
Date: Tue, 13 Apr 2021 21:54:26 +0200
Subject: [PATCH] Fix various Sphinx warnings
---
docs/cli.rst | 4 ++--
docs/persistent-identifiers.rst | 36 ++++++++++++++-----------------
swh/model/cli.py | 4 ++--
swh/model/identifiers.py | 38 ++++++++++++++++-----------------
swh/model/merkle.py | 16 ++++++++------
5 files changed, 47 insertions(+), 51 deletions(-)
diff --git a/docs/cli.rst b/docs/cli.rst
index 654111f6..0826a01d 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -2,5 +2,5 @@ Command-line interface
======================
.. 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
index 2f20cf18..2cb27e5b 100644
--- a/docs/persistent-identifiers.rst
+++ b/docs/persistent-identifiers.rst
@@ -257,34 +257,30 @@ Identifiers with qualifiers
---------------------------
* The following `SWHID
- <https://archive.softwareheritage.org/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>`_
+ <https://archive.softwareheritage.org/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>`__
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
- <https://archive.softwareheritage.org/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:
-
-.. 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/
+ <https://archive.softwareheritage.org/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
index effdf8a8..091f8aba 100644
--- a/swh/model/cli.py
+++ b/swh/model/cli.py
@@ -218,7 +218,7 @@ def identify_object(obj_type, follow_symlinks, exclude_patterns, obj) -> str:
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 @@ def identify(
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
index 563da9e6..daa92e75 100644
--- a/swh/model/identifiers.py
+++ b/swh/model/identifiers.py
@@ -47,7 +47,7 @@ class ObjectType(enum.Enum):
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 @@ def raw_extrinsic_metadata_identifier(metadata: Dict[str, Any]) -> str:
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 @@ def raw_extrinsic_metadata_identifier(metadata: Dict[str, Any]) -> str:
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
index e84ef9d9..098c8723 100644
--- 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 @@ class MerkleNode(dict, metaclass=abc.ABCMeta):
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__()
--
GitLab