diff --git a/docs/faq/index.rst b/docs/faq/index.rst --- a/docs/faq/index.rst +++ b/docs/faq/index.rst @@ -175,8 +175,8 @@ What tests I should run before committing the code? --------------------------------------------------- -Mostly run `tox` (or `pytest`) to run the unit tests suite. When you will propose a -patch in our forge, the continuous integration factory will trigger a build (using `tox` +Mostly run ``tox`` (or ``pytest``) to run the unit tests suite. When you will propose a +patch in our forge, the continuous integration factory will trigger a build (using ``tox`` as well). I am getting errors while trying to commit. What is going wrong? @@ -204,8 +204,8 @@ --------------------------------------------------- Any new feature should include documentation in the form of comments and/or docstrings. -Ideally, they should also be documented in plain English in the repository's `docs/` -folder if relevant to a single package, or in the main `swh-docs` repository if it is a +Ideally, they should also be documented in plain English in the repository's :file:`docs/` +folder if relevant to a single package, or in the main ``swh-docs`` repository if it is a transversal feature. .. _faq_api: diff --git a/docs/glossary.rst b/docs/glossary.rst --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -123,8 +123,8 @@ Metadata about software that is shipped as part of the source code of the software itself or as part of related artifacts (e.g., revisions, releases, etc). For example, metadata that is shipped in `PKG-INFO` files - for Python packages, `pom.xml` for Maven-based Java projects, - `debian/control` for Debian packages, `metadata.json` for NPM, etc. + for Python packages, :file:`pom.xml` for Maven-based Java projects, + :file:`debian/control` for Debian packages, :file:`metadata.json` for NPM, etc. See also: :term:`extrinsic metadata`, :ref:`architecture-metadata`. diff --git a/docs/journal.rst b/docs/journal.rst --- a/docs/journal.rst +++ b/docs/journal.rst @@ -184,19 +184,19 @@ Message format: -- `message` [bytes] the commit message for the revision -- `author` [dict] the author of the revision -- `committer` [dict] the committer of the revision -- `date` [gitdate] the revision date -- `committer_date` [gitdate] the revision commit date -- `type` [string] the type of the revision (can be "git", "tar", "dsc", "svn", "hg") -- `directory` [bytes] the intrinsic identifier of the directory this revision links to -- `synthetic` [bool] whether this :py:class:`swh.model.model.Revision` is synthetic or not, -- `metadata` [bytes] the metadata linked to this :py:class:`swh.model.model.Revision` (not part of the +- ``message`` [bytes] the commit message for the revision +- ``author`` [dict] the author of the revision +- ``committer`` [dict] the committer of the revision +- ``date`` [gitdate] the revision date +- ``committer_date`` [gitdate] the revision commit date +- ``type`` [string] the type of the revision (can be "git", "tar", "dsc", "svn", "hg") +- ``directory`` [bytes] the intrinsic identifier of the directory this revision links to +- ``synthetic`` [bool] whether this :py:class:`swh.model.model.Revision` is synthetic or not, +- ``metadata`` [bytes] the metadata linked to this :py:class:`swh.model.model.Revision` (not part of the intrinsic identifier computation), -- `parents` [list[bytes]] list of parent :py:class:`swh.model.model.Revision` intrinsic identifiers -- `id` [bytes] intrinsic identifier of the :py:class:`swh.model.model.Revision` -- `extra_headers` [list[(bytes, bytes)]] TODO +- ``parents`` [list[bytes]] list of parent :py:class:`swh.model.model.Revision` intrinsic identifiers +- ``id`` [bytes] intrinsic identifier of the :py:class:`swh.model.model.Revision` +- ``extra_headers`` [list[(bytes, bytes)]] TODO Example: @@ -248,13 +248,13 @@ Message format: -- `sha1` [bytes] SHA1 of the :py:class:`swh.model.model.Content` -- `sha1_git` [bytes] SHA1_GIT of the :py:class:`swh.model.model.Content` -- `sha256` [bytes] SHA256 of the :py:class:`swh.model.model.Content` -- `blake2s256` [bytes] Blake2S256 hash of the :py:class:`swh.model.model.Content` -- `length` [int] length of the :py:class:`swh.model.model.Content` -- `status` [string] visibility status of the :py:class:`swh.model.model.Content` (can be "visible" or "hidden") -- `ctime` [timestamp] creation date of the :py:class:`swh.model.model.Content` (i.e. date at which this +- ``sha1`` [bytes] SHA1 of the :py:class:`swh.model.model.Content` +- ``sha1_git`` [bytes] SHA1_GIT of the :py:class:`swh.model.model.Content` +- ``sha256`` [bytes] SHA256 of the :py:class:`swh.model.model.Content` +- ``blake2s256`` [bytes] Blake2S256 hash of the :py:class:`swh.model.model.Content` +- ``length`` [int] length of the :py:class:`swh.model.model.Content` +- ``status`` [string] visibility status of the :py:class:`swh.model.model.Content` (can be "visible" or "hidden") +- ``ctime`` [timestamp] creation date of the :py:class:`swh.model.model.Content` (i.e. date at which this :py:class:`swh.model.model.Content` has been seen for the first time in the |swh| Archive). Example: @@ -273,25 +273,25 @@ -`swh.journal.objects.skipped_content` -+++++++++++++++++++++++++++++++++++++ +``swh.journal.objects.skipped_content`` ++++++++++++++++++++++++++++++++++++++++ Topic for :py:class:`swh.model.model.SkippedContent` objects. Message format: -- `sha1` [bytes] SHA1 of the :py:class:`swh.model.model.SkippedContent` -- `sha1_git` [bytes] SHA1 of the :py:class:`swh.model.model.SkippedContent` -- `sha256` [bytes] SHA1 of the :py:class:`swh.model.model.SkippedContent` -- `blake2s256` [bytes] SHA1 of the :py:class:`swh.model.model.SkippedContent` -- `length` [int] length of the :py:class:`swh.model.model.SkippedContent` -- `status` [string] visibility status of the +- ``sha1`` [bytes] SHA1 of the :py:class:`swh.model.model.SkippedContent` +- ``sha1_git`` [bytes] SHA1 of the :py:class:`swh.model.model.SkippedContent` +- ``sha256`` [bytes] SHA1 of the :py:class:`swh.model.model.SkippedContent` +- ``blake2s256`` [bytes] SHA1 of the :py:class:`swh.model.model.SkippedContent` +- ``length`` [int] length of the :py:class:`swh.model.model.SkippedContent` +- ``status`` [string] visibility status of the :py:class:`swh.model.model.SkippedContent` (can only be "absent") -- `reason` [string] message indicating the reason for this content to be a +- ``reason`` [string] message indicating the reason for this content to be a :py:class:`swh.model.model.SkippedContent` (rather than a :py:class:`swh.model.model.Content`) -- `ctime` [timestamp] creation date of the +- ``ctime`` [timestamp] creation date of the :py:class:`swh.model.model.SkippedContent` (i.e. date at which this :py:class:`swh.model.model.SkippedContent` has been seen for the first time in the |swh| Archive) @@ -321,14 +321,14 @@ Message format: -- `entries` [list[dict]] list of directory entries -- `id` [bytes] intrinsic identifier of this :py:class:`swh.model.model.Directory` +- ``entries`` [list[dict]] list of directory entries +- ``id`` [bytes] intrinsic identifier of this :py:class:`swh.model.model.Directory` with directory entries being dictionaries: -- `name` [bytes] name of the directory entry -- `type` [string] type of directory entry (can be "file", "dir" or "rev") -- `perms` [int] permissions for this directory entry +- ``name`` [bytes] name of the directory entry +- ``type`` [string] type of directory entry (can be "file", "dir" or "rev") +- ``perms`` [int] permissions for this directory entry Example: @@ -367,14 +367,14 @@ ` for more details. -`swh.journal.objects.origin` -++++++++++++++++++++++++++++ +``swh.journal.objects.origin`` +++++++++++++++++++++++++++++++ Topic for :py:class:`swh.model.model.Origin` objects. Message format: -- `url` [string] URL of the :py:class:`swh.model.model.Origin` +- ``url`` [string] URL of the :py:class:`swh.model.model.Origin` Example: @@ -385,17 +385,17 @@ } -`swh.journal.objects.origin_visit` -++++++++++++++++++++++++++++++++++ +``swh.journal.objects.origin_visit`` +++++++++++++++++++++++++++++++++++++ Topic for :py:class:`swh.model.model.OriginVisit` objects. Message format: -- `origin` [string] URL of the visited :py:class:`swh.model.model.Origin` -- `date` [timestamp] date of the visit -- `type` [string] type of the loader used to perform the visit -- `visit` [int] number of the visit for this `origin` +- ``origin`` [string] URL of the visited :py:class:`swh.model.model.Origin` +- ``date`` [timestamp] date of the visit +- ``type`` [string] type of the loader used to perform the visit +- ``visit`` [int] number of the visit for this ``origin`` Example: @@ -409,20 +409,20 @@ } -`swh.journal.objects.origin_visit_status` -+++++++++++++++++++++++++++++++++++++++++ +``swh.journal.objects.origin_visit_status`` ++++++++++++++++++++++++++++++++++++++++++++ Topic for :py:class:`swh.model.model.OriginVisitStatus` objects. Message format: -- `origin` [string] URL of the visited :py:class:`swh.model.model.Origin` -- `visit` [int] number of the visit for this `origin` this status concerns -- `date` [timestamp] date of the visit status update -- `status` [string] status (can be "created", "ongoing", "full" or "partial"), -- `snapshot` [bytes] identifier of the :py:class:`swh.model.model.Snaphot` this - visit resulted in (if `status` is "full" or "partial") -- `metadata`: deprecated +- ``origin`` [string] URL of the visited :py:class:`swh.model.model.Origin` +- ``visit`` [int] number of the visit for this ``origin`` this status concerns +- ``date`` [timestamp] date of the visit status update +- ``status`` [string] status (can be "created", "ongoing", "full" or "partial"), +- ``snapshot`` [bytes] identifier of the :py:class:`swh.model.model.Snaphot` this + visit resulted in (if ``status`` is "full" or "partial") +- ``metadata``: deprecated Example: @@ -447,16 +447,16 @@ :ref:`extrinsic-metadata-specification` for more details on the Extrinsic Metadata model. -`swh.journal.objects.metadata_authority` -++++++++++++++++++++++++++++++++++++++++ +``swh.journal.objects.metadata_authority`` +++++++++++++++++++++++++++++++++++++++++++ Topic for :py:class:`swh.model.model.MetadataAuthority` objects. Message format: -- `type` [string] -- `url` [string] -- `metadata` [dict] +- ``type`` [string] +- ``url`` [string] +- ``metadata`` [dict] Examples: @@ -476,16 +476,16 @@ -`swh.journal.objects.metadata_fetcher` -++++++++++++++++++++++++++++++++++++++ +``swh.journal.objects.metadata_fetcher`` +++++++++++++++++++++++++++++++++++++++++ Topic for :py:class:`swh.model.model.MetadataFetcher` objects. Message format: -- `type` [string] -- `version` [string] -- `metadata` [dict] +- ``type`` [string] +- ``version`` [string] +- ``metadata`` [dict] Example: @@ -499,27 +499,27 @@ -`swh.journal.objects.raw_extrinsic_metadata` -++++++++++++++++++++++++++++++++++++++++++++ +``swh.journal.objects.raw_extrinsic_metadata`` +++++++++++++++++++++++++++++++++++++++++++++++ Topic for :py:class:`swh.model.model.RawExtrinsicMetadata` objects. Message format: -- `type` [string] -- `target` [string] -- `discovery_date` [timestamp] -- `authority` [dict] -- `fetcher` [dict] -- `format` [string] -- `metadata` [bytes] -- `origin` [string] -- `visit` [int] -- `snapshot` [SWHID] -- `release` [SWHID] -- `revision` [SWHID] -- `path` [bytes] -- `directory` [SWHID] +- ``type`` [string] +- ``target`` [string] +- ``discovery_date`` [timestamp] +- ``authority`` [dict] +- ``fetcher`` [dict] +- ``format`` [string] +- ``metadata`` [bytes] +- ``origin`` [string] +- ``visit`` [int] +- ``snapshot`` [SWHID] +- ``release`` [SWHID] +- ``revision`` [SWHID] +- ``path`` [bytes] +- ``directory`` [SWHID] Example: @@ -564,13 +564,13 @@ Integer +++++++ -For long integers (that do not fit in the `[-(2**63), 2 ** 64 - 1]` range), a +For long integers (that do not fit in the ``[-(2**63), 2 ** 64 - 1]`` range), a custom `extended type`_ based encoding scheme is used. -The `type` information can be: +The ``type`` information can be: -- `1` for positive (possibly long) integers, -- `2` for negative (possibly long) integers. +- ``1`` for positive (possibly long) integers, +- ``2`` for negative (possibly long) integers. The payload is simply the bytes (big endian) representation of the absolute value (always positive). @@ -579,8 +579,8 @@ values are small so they will actually be encoded using the default msgpack format for integers): -- `12345` would be encoded as the extension value `[1, [0x30, 0x39]]` (aka `0xd5013039`) -- `-42` would be encoded as the extension value `[2, [0x2A]]` (aka `0xd4022a`) +- ``12345`` would be encoded as the extension value ``[1, [0x30, 0x39]]`` (aka ``0xd5013039``) +- ``-42`` would be encoded as the extension value ``[2, [0x2A]]`` (aka ``0xd4022a``) Datetime @@ -594,12 +594,12 @@ git repositories, a custom encoding is required. These dates (coming from the git data model) are encoded as a dictionary with: - - `timestamp` [dict] POSIX timestamp of the date, as a dictionary with 2 keys - (`seconds` and `microseconds`) + - ``timestamp`` [dict] POSIX timestamp of the date, as a dictionary with 2 keys + (``seconds`` and ``microseconds``) - - `offset` [int] offset of the date (in minutes) + - ``offset`` [int] offset of the date (in minutes) - - `negative_utc` [bool] only True for the very edge case where the date has a + - ``negative_utc`` [bool] only True for the very edge case where the date has a zero but negative offset value (which does not makes much sense, but technically the git format permits) @@ -613,12 +613,12 @@ 'negative_utc': False } - These are denoted as `gitdate` below. + These are denoted as ``gitdate`` below. - other dates (resulting of the |swh| processing stack) are encoded using msgpack's Timestamp_ extended type. - These are denoted as `timestamp` below. + These are denoted as ``timestamp`` below. Note that these dates used to be encoded as a dictionary (beware: keys are bytes): @@ -660,8 +660,8 @@ } -where the `` is computed from original values as a sha256 of the -original's `fullname`. +where the ```` is computed from original values as a sha256 of the +original's ``fullname``.