diff --git a/docs/dev-info.rst b/docs/dev-info.rst --- a/docs/dev-info.rst +++ b/docs/dev-info.rst @@ -22,14 +22,14 @@ To simplify the use, the following makefile targets can be used: schema -~~~~~~ +^^^^^^ .. code:: shell make db-create db-prepare db-migrate data -~~~~ +^^^^ Once the db is created, you need some data to be injected (request types, client, collection, etc...): @@ -65,7 +65,7 @@ url: https://hal.inria.fr drop -~~~~ +^^^^ For information, you can drop the db: @@ -80,7 +80,7 @@ properly. Configuration -~~~~~~~~~~~~~ +^^^^^^^^^^^^^ **``{/etc/softwareheritage | ~/.config/swh | ~/.swh}``/deposit/server.yml**: @@ -101,7 +101,7 @@ max_upload_size: 20971520 Run -~~~ +^^^ Run the local server, using the default configuration file: @@ -118,7 +118,7 @@ This is more close to what's actually running in production. Configuration -~~~~~~~~~~~~~ +^^^^^^^^^^^^^ This expects the same file describes in the previous chapter. Plus, an additional private section file containing private information that is @@ -147,7 +147,7 @@ password: user-password Run -~~~ +^^^ .. code:: shell diff --git a/docs/metadata.rst b/docs/metadata.rst --- a/docs/metadata.rst +++ b/docs/metadata.rst @@ -54,7 +54,7 @@ -------- Using only Atom -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ .. code:: xml @@ -73,7 +73,7 @@ Using Atom with CodeMeta -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: xml @@ -138,7 +138,7 @@ Using Atom with DublinCore and CodeMeta (multi-schema entry) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code:: xml diff --git a/docs/specs/blueprint.rst b/docs/specs/blueprint.rst --- a/docs/specs/blueprint.rst +++ b/docs/specs/blueprint.rst @@ -1,5 +1,5 @@ Use cases ---------- +========= The general idea is that a deposit can be created either in a single request or by multiple requests to allow the user to add elements to the deposit piece @@ -52,7 +52,7 @@ Deposit creation -~~~~~~~~~~~~~~~~ +---------------- From client's deposit repository server to SWH's repository server: @@ -109,7 +109,7 @@ Updating an existing deposit -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"""""""""""""""""""""""""""" 5. Client updates existing deposit through the *update uris* (one or more POST or PUT requests to either the *edit-media iri* or *edit iri*). @@ -138,7 +138,7 @@ Schema representation -^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""" Scenario: updating a deposit via SWORDv2_ protocol: @@ -147,7 +147,7 @@ Deleting deposit (or associated archive, or associated metadata) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 6. Deposit deletion is possible as long as the deposit is still in ``partial`` state. @@ -166,13 +166,13 @@ Client asks for operation status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"""""""""""""""""""""""""""""""" 7. Operation status can be read through a GET query to the *state iri*. Server: Triggering deposit checks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""""""""""""""""" Once the status ``deposited`` is reached for a deposit, checks for the associated archive(s) and metadata will be triggered. If those checks @@ -181,7 +181,7 @@ Server: Triggering deposit load -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""""""""""""""" Once the status ``verified`` is reached for a deposit, loading the deposit with its associated metadata will be triggered. diff --git a/docs/specs/protocol-reference.rst b/docs/specs/protocol-reference.rst --- a/docs/specs/protocol-reference.rst +++ b/docs/specs/protocol-reference.rst @@ -1,7 +1,7 @@ .. _deposit-protocol: Protocol reference -~~~~~~~~~~~~~~~~~~ +================== The swh-deposit protocol is an extension SWORDv2_ protocol, and the swh-deposit client and server should work with any other SWORDv2-compliant @@ -17,10 +17,10 @@ Origin creation with the ```` tag -=========================================================== +----------------------------------------------------------- Motivation ----------- +^^^^^^^^^^ This is the main extension we define. This tag is used after a deposit is completed, to load it in the Software Heritage @@ -33,7 +33,7 @@ have an URL. Usage ------ +^^^^^ Instead, clients are expected to provide the origin URL themselves, by adding a tag in the Atom entry they submit to the server, like this: @@ -59,7 +59,7 @@ the source code artifacts of this deposit. Semantics of origin URLs ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ Origin URLs must be unique to an origin, ie. to a software project. The exact definition of a "software project" is left to the clients of the deposit. @@ -80,7 +80,7 @@ ``https://example.org/foo/``. Fallbacks ---------- +^^^^^^^^^ If the ```` is not provided (either because they are generic SWORDv2 implementations or old implementations of an swh-deposit client), the server @@ -93,7 +93,7 @@ Adding releases to an origin, with the ```` tag -========================================================================= +------------------------------------------------------------------------- When depositing a source code artifact for an origin (ie. software project) that was already deposited before, clients should not use ````, @@ -128,10 +128,10 @@ Metadata -======== +-------- Format ------- +^^^^^^ While the SWORDv2 specification recommends the use of DublinCore_, we prefer the CodeMeta_ vocabulary, as we already use it in other components @@ -200,7 +200,7 @@ .. _mandatory-attributes: Mandatory attributes --------------------- +^^^^^^^^^^^^^^^^^^^^ All deposits must include: @@ -213,7 +213,7 @@ .. _metatadata-only-deposit Metadata-only deposit -===================== +--------------------- The swh-deposit server can also be without a source code artifact, but only to provide metadata that describes an arbitrary origin or object in 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 @@ -1,10 +1,10 @@ .. _spec-metadata-deposit: The metadata-only deposit -^^^^^^^^^^^^^^^^^^^^^^^^^ +========================= Goal -==== +---- A client may wish to deposit only metadata about an origin or object already present in the Software Heritage archive. @@ -14,7 +14,7 @@ the metadata about an object in the archive. Requirements -============ +------------ 1. Create a metadata-only deposit through a :ref:`POST request` 2. It is composed of ONLY one Atom XML document @@ -35,7 +35,7 @@ .. _qualifiers: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#qualifiers A complete metadata example -=========================== +--------------------------- The reference element is included in the metadata xml atomEntry under the swh namespace: @@ -72,14 +72,14 @@ References -========== +---------- The metadata reference can be either on: - an origin - a graph object (core SWHID with or without qualifiers) Origins -------- +^^^^^^^ The metadata may be on an origin, identified by the origin's URL: @@ -92,7 +92,7 @@ Graph objects -------------- +^^^^^^^^^^^^^ It may also reference an object in the `SWH graph `: contents, directories, revisions, releases, and snapshots: @@ -129,7 +129,7 @@ Loading procedure -================= +----------------- In this case, the metadata-deposit will be injected as a metadata entry of the relevant object, with the information about the contributor of the deposit. diff --git a/docs/user-manual.rst b/docs/user-manual.rst --- a/docs/user-manual.rst +++ b/docs/user-manual.rst @@ -340,7 +340,7 @@ piece by piece. The steps to create a multisteps deposit: 1. Create an partial deposit -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"""""""""""""""""""""""""""" First use the ``--partial`` argument to declare there is more to come @@ -352,7 +352,7 @@ 2. Add content or metadata to the deposit -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""""""""""""""""""""""""" Continue the deposit by using the ``--deposit-id`` argument given as a response for the first step. You can continue adding content or metadata while you use @@ -378,7 +378,7 @@ 3. Finalize deposit -~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""" On your last addition (same command as before), by not declaring it ``--partial``, the deposit will be considered completed. Its status will be