diff --git a/docs/README.rst b/docs/README.rst --- a/docs/README.rst +++ b/docs/README.rst @@ -25,7 +25,7 @@ without having to pass through an intermediate collaborative development platform, which is already harvested by SWH (e.g GitHub, Gitlab, etc.). -This mechanism is the `deposit`. +This mechanism is the ``deposit``. The main idea is the deposit is an authenticated access to an API allowing the user to provide source code artifacts -- with metadata -- to be ingested in the SWH Archive. The @@ -61,11 +61,11 @@ Read the :ref:`deposit-metadata` chapter to get more details on what metadata are supported when doing a deposit. -See :ref:`swh-deposit-dev-env` if you want to hack the code of the `swh.deposit` module. +See :ref:`swh-deposit-dev-env` if you want to hack the code of the ``swh.deposit`` module. See :ref:`swh-deposit-prod-env` if you want to deploy your own copy of the `swh.deposit` stack. .. _codemeta: https://codemeta.github.io/ -.. _`SWORD v2`: http://swordapp.org/sword-v2/ +.. _SWORD v2: http://swordapp.org/sword-v2/ diff --git a/docs/api/use-cases.rst b/docs/api/use-cases.rst --- a/docs/api/use-cases.rst +++ b/docs/api/use-cases.rst @@ -7,17 +7,17 @@ or by multiple requests to allow the user to add elements to the deposit piece by piece (be it the deposited data or the metadata describing it). -An update request that does not have the `In-Progress: true` HTTP header will -de facto declare the deposit as *completed* (aka in the `deposited` status; see +An update request that does not have the ``In-Progress: true`` HTTP header will +de facto declare the deposit as *completed* (aka in the ``deposited`` status; see below) and thus ready for ingestion. Once the deposit is declared *complete* by the user, the server performs a few validation checks. Then, if valid, schedule the ingestion of the deposited data in the Software Heritage Archive (SWH). -There is a `status` property attached to a deposit allowing to follow the +There is a ``status`` property attached to a deposit allowing to follow the processing workflow of the deposit. For example, when this ingestion task -completes successfully, the deposit is marked as `done`. +completes successfully, the deposit is marked as ``done``. Possible deposit statuses are: diff --git a/docs/api/user-manual.rst b/docs/api/user-manual.rst --- a/docs/api/user-manual.rst +++ b/docs/api/user-manual.rst @@ -4,7 +4,7 @@ =========== This is a guide for how to prepare and push a software deposit with -the `swh deposit` commands. +the ``swh deposit`` commands. Requirements @@ -20,7 +20,7 @@ `_ [#f1]_ and will be used in the examples below. Once you have an account, you should get a set of access credentials as a -`login` and a `password` (identified as ```` and ```` in the +``login`` and a ``password`` (identified as ```` and ```` in the remaining of this document). A deposit account also comes with a "provider URL" which is used by SWH to build the :term:`Origin URL` of deposits created using this account. @@ -29,7 +29,7 @@ Installation ------------ -To install the `swh.deposit` command line tools, you need a working Python 3.7+ +To install the ``swh.deposit`` command line tools, you need a working Python 3.7+ environment. It is strongly recommended you use a `virtualenv `_ for this. @@ -73,8 +73,8 @@ - zip: common zip archive (no multi-disk zip files). - tar: tar archive without compression or optionally any of the - following compression algorithm gzip (`.tar.gz`, `.tgz`), bzip2 - (`.tar.bz2`) , or lzma (`.tar.lzma`) + following compression algorithm gzip (``.tar.gz``, ``.tgz``), bzip2 + (``.tar.bz2``) , or lzma (``.tar.lzma``) * (Optional) prepare a metadata file (more details :ref:`deposit-metadata`): @@ -187,8 +187,8 @@ loading is a failure -When you push a deposit, it is either in the `deposited` state or in the -`partial` state if you asked for a partial upload. +When you push a deposit, it is either in the ``deposited`` state or in the +``partial`` state if you asked for a partial upload. @@ -207,7 +207,7 @@ * archive's path (example: ``--archive path/to/archive-name.tgz``) * metadata file path (example: ``--metadata path/to/metadata.xml``) -to the `swh deposit upload` command. +to the ``swh deposit upload`` command. @@ -241,14 +241,14 @@ The returned value is a JSON dict, in which you will notably find the deposit id (needed to check for its status later on) and the current status, which -should be `deposited` if no error has occurred. +should be ``deposited`` if no error has occurred. Note: As the deposit is in ``deposited`` status, you can no longer update the deposit after this query. It will be answered with a 403 (Forbidden) answer. If something went wrong, an equivalent response will be given with the -`error` and `detail` keys explaining the issue, e.g.: +``error`` and ``detail`` keys explaining the issue, e.g.: .. code:: console @@ -262,8 +262,8 @@ } -Once the deposit has been done, you can check its status using the `swh deposit -status` command: +Once the deposit has been done, you can check its status using the ``swh deposit +status`` command: .. code:: console @@ -313,7 +313,7 @@ * arguments: ``--username 'name' --password 'pass'`` as credentials * metadata file path (example: ``--metadata path/to/metadata.xml``) -to the `swh deposit metadata-only` command. +to the ``swh deposit metadata-only`` command. Example: diff --git a/docs/endpoints/collection.rst b/docs/endpoints/collection.rst --- a/docs/endpoints/collection.rst +++ b/docs/endpoints/collection.rst @@ -5,7 +5,7 @@ .. http:post:: /1/(str:collection-name)/ - Create deposit in a collection which name is `collection-name`. + Create deposit in a collection which name is ``collection-name``. The client sends a deposit request to a specific collection with: @@ -81,7 +81,7 @@ :reqheader Content-Disposition: attachment; filename=[filename]; the filename parameter must be text (ascii); for the metadata file set name parameter to 'atom'. - :reqheader In-progress: `true` if not final; `false` when final request. + :reqheader In-progress: ``true`` if not final; ``false`` when final request. :statuscode 201: success for deposit on POST :statuscode 401: Unauthorized :statuscode 404: access to an unknown collection diff --git a/docs/endpoints/update-media.rst b/docs/endpoints/update-media.rst --- a/docs/endpoints/update-media.rst +++ b/docs/endpoints/update-media.rst @@ -20,7 +20,7 @@ :reqheader Content-MD5: md5 checksum hex encoded of the tarball :reqheader Content-Disposition: attachment; filename=[filename] ; the filename parameter must be text (ascii) - :reqheader In-progress: `true` if not final; `false` when final request. + :reqheader In-progress: ``true`` if not final; ``false`` when final request. :statuscode 204: success without payload on PUT :statuscode 201: success for deposit on POST :statuscode 401: Unauthorized diff --git a/docs/internals/prod-environment.rst b/docs/internals/prod-environment.rst --- a/docs/internals/prod-environment.rst +++ b/docs/internals/prod-environment.rst @@ -12,7 +12,7 @@ correct (the checker), another worker service dedicated to actually ingest the deposit into the swh archive. - - client: a python script `swh deposit` command line interface. + - client: a python script ``swh deposit`` command line interface. All those are packaged in 3 separated debian packages, created and uploaded to the swh debian repository. The deposit server and workers configuration are managed by puppet @@ -33,7 +33,7 @@ Environment (production/staging) -------------------------------- -`SWH_CONFIG_FILENAME` must be defined and target the deposit server configuration file. +``SWH_CONFIG_FILENAME`` must be defined and target the deposit server configuration file. So either 1. prefix the following commands or 2. export the environment variable in your shell session. For the remaining part of the documentation, we assume 2. has been configured. @@ -58,7 +58,7 @@ The deposit can be configured to use either the 1. django basic authentication framework or the 2. swh keycloak instance. If the server uses 2., the password is managed by -keycloak so the option `--password`` is ignored. +keycloak so the option ``--password`` is ignored. * basic diff --git a/docs/specs/spec-loading.rst b/docs/specs/spec-loading.rst --- a/docs/specs/spec-loading.rst +++ b/docs/specs/spec-loading.rst @@ -161,8 +161,8 @@ vocabulary. The following CodeMeta terms implies that the artifact is a release: -- `releaseNotes` -- `softwareVersion` +- ``releaseNotes`` +- ``softwareVersion`` If present, a release artifact will be created with the mapping below: diff --git a/docs/specs/spec-meta-deposit.rst b/docs/specs/spec-meta-deposit.rst --- a/docs/specs/spec-meta-deposit.rst +++ b/docs/specs/spec-meta-deposit.rst @@ -29,7 +29,7 @@ - directory - content 7. The SWHID MAY be a :ref:`core identifier ` with or without :ref:`qualifiers ` -8. The SWHID MUST NOT reference a fragment of code with the classifier `lines` +8. The SWHID MUST NOT reference a fragment of code with the classifier ``lines`` A complete metadata example ---------------------------