diff --git a/docs/README.rst b/docs/README.rst --- a/docs/README.rst +++ b/docs/README.rst @@ -58,8 +58,8 @@ See the :ref:`deposit-api-specifications` reference pages of the SWORDv2 API implementation in `swh.deposit` if you want to do upload deposits using HTTP requests. -Read the :ref:`metadata` chapter to get more details on what metadata are supported when -doing a deposit. +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. diff --git a/docs/api/api-documentation.rst b/docs/api/api-documentation.rst --- a/docs/api/api-documentation.rst +++ b/docs/api/api-documentation.rst @@ -58,17 +58,13 @@ Data is sent and received as XML (as specified in the SWORD 2.0 specification). -.. include:: ../endpoints/service-document.rst - -.. include:: ../endpoints/collection.rst - -.. include:: ../endpoints/update-media.rst - -.. include:: ../endpoints/update-metadata.rst - -.. include:: ../endpoints/status.rst - -.. include:: ../endpoints/content.rst +.. toctree:: + ../endpoints/service-document.rst + ../endpoints/collection.rst + ../endpoints/update-media.rst + ../endpoints/update-metadata.rst + ../endpoints/status.rst + ../endpoints/content.rst Possible errors: 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 @@ -238,7 +238,7 @@ archive. This use case is triggered by a ```` tag in the Atom document, -see the :ref:`protocol reference ` for details. +see the :ref:`protocol reference ` for details. In the current implementation, these deposits are loaded (or rejected) immediately after a request without ``In-Progress: true`` is made, 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 @@ -64,7 +64,7 @@ $ sudo apt install jq -.. _prepare_deposit +.. _prepare-deposit: Prepare a deposit ----------------- @@ -292,7 +292,7 @@ .. code:: xml - diff --git a/docs/cli.rst b/docs/cli.rst --- a/docs/cli.rst +++ b/docs/cli.rst @@ -30,6 +30,6 @@ :prog: swh deposit :nested: full -.. click:: swh.deposit.cli.client:metadata-only +.. click:: swh.deposit.cli.client:metadata_only :prog: swh deposit :nested: full diff --git a/docs/internals/authentication.rst b/docs/internals/authentication.rst --- a/docs/internals/authentication.rst +++ b/docs/internals/authentication.rst @@ -16,7 +16,7 @@ authorized, the deposit client is allowed to continue its deposit. Otherwise, a 401 response is returned to the client. -.. figure:: images/deposit-authentication-basic.svg +.. figure:: ../images/deposit-authentication-basic.svg :alt: Basic Authentication @@ -38,7 +38,7 @@ If any issue arises during one of the authentication check, the client receives a 401 response (unauthorized). -.. figure:: images/deposit-authentication-keycloak.svg +.. figure:: ../images/deposit-authentication-keycloak.svg :alt: Keycloak Authentication .. _keycloak: https://www.keycloak.org/ diff --git a/docs/internals/loading-workflow.rst b/docs/internals/loading-workflow.rst --- a/docs/internals/loading-workflow.rst +++ b/docs/internals/loading-workflow.rst @@ -1,7 +1,7 @@ Loading workflow ================ -This section complements the :ref:`deposit-use-case` documentation, +This section complements the :ref:`deposit-use-cases` documentation, by detailing how deposits are handled internally after clients deposited them. Reception 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 @@ -157,7 +157,7 @@ "email": "foo@example.org" }, { - "name": Author 2" + "name": "Author 2" } ] } @@ -210,7 +210,7 @@ We also highly recommend their CodeMeta equivalent, and any other relevant metadata, but this is not enforced. -.. _metatadata-only-deposit: +.. _metadata-only-deposit: Metadata-only deposit --------------------- diff --git a/swh/deposit/utils.py b/swh/deposit/utils.py --- a/swh/deposit/utils.py +++ b/swh/deposit/utils.py @@ -146,22 +146,28 @@ def parse_swh_reference(metadata: Dict,) -> Optional[Union[QualifiedSWHID, str]]: - """Parse swh reference within the metadata dict (or origin) reference if found, None - otherwise. + """Parse swh reference within the metadata dict (or origin) reference if found, + None otherwise. - - - - - + .. code-block:: xml + + + + + + or: - - - - + .. code-block:: xml + + + + + + + Args: + metadata: result of parsing an Atom document with :func:`parse_xml` Raises: ValidationError in case the swhid referenced (if any) is invalid