diff --git a/docs/README.rst b/docs/README.rst --- a/docs/README.rst +++ b/docs/README.rst @@ -61,9 +61,9 @@ Read the :ref:`metadata` chapter to get more details on what metadata are supported when doing a deposit. -See :ref:`swh-deposit-dev` 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-deployment` if you want to deploy your own copy of the +See :ref:`swh-deposit-prod-env` if you want to deploy your own copy of the `swh.deposit` stack. diff --git a/docs/spec-api.rst b/docs/api/api-documentation.rst rename from docs/spec-api.rst rename to docs/api/api-documentation.rst diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,13 @@ +.. _swh-deposit-api: + +Deposit API +=========== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + user-manual + api-documentation + metadata + use-cases diff --git a/docs/metadata.rst b/docs/api/metadata.rst rename from docs/metadata.rst rename to docs/api/metadata.rst diff --git a/docs/specs/blueprint.rst b/docs/api/use-cases.rst rename from docs/specs/blueprint.rst rename to docs/api/use-cases.rst diff --git a/docs/user-manual.rst b/docs/api/user-manual.rst rename from docs/user-manual.rst rename to docs/api/user-manual.rst diff --git a/docs/cli.rst b/docs/cli.rst --- a/docs/cli.rst +++ b/docs/cli.rst @@ -17,6 +17,8 @@ :prog: swh deposit admin :nested: full +.. _swh-deposit-cli-client: + Deposit client tools -------------------- diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -6,13 +6,9 @@ :maxdepth: 2 :caption: Contents: - user-manual - metadata - spec-api - dev-info - sys-info + api/index + internals/index specs/index - tests/tests_HAL.rst Reference Documentation @@ -23,4 +19,3 @@ cli /apidoc/swh.deposit - authentication.rst diff --git a/docs/authentication.rst b/docs/internals/authentication.rst rename from docs/authentication.rst rename to docs/internals/authentication.rst diff --git a/docs/dev-info.rst b/docs/internals/dev-environment.rst rename from docs/dev-info.rst rename to docs/internals/dev-environment.rst --- a/docs/dev-info.rst +++ b/docs/internals/dev-environment.rst @@ -1,7 +1,7 @@ -.. _swh-deposit-dev: +.. _swh-deposit-dev-env: -Hacking on swh-deposit -====================== +Running swh-deposit locally +=========================== There are multiple modes to run and test the server locally: diff --git a/docs/internals/index.rst b/docs/internals/index.rst new file mode 100644 --- /dev/null +++ b/docs/internals/index.rst @@ -0,0 +1,14 @@ +.. _swh-deposit-internals: + +Deposit internals +================= + +This chapter describes how swh-deposit works internally, +and how to run it (either in production or locally for development). + +.. toctree:: + :maxdepth: 1 + + dev-environment + prod-environment + authentication diff --git a/docs/sys-info.rst b/docs/internals/prod-environment.rst rename from docs/sys-info.rst rename to docs/internals/prod-environment.rst --- a/docs/sys-info.rst +++ b/docs/internals/prod-environment.rst @@ -1,7 +1,7 @@ -.. _swh-deposit-deployment: +.. _swh-deposit-prod-env: -Deployment -========== +Production deployment +===================== The deposit is architectured around 3 parts: @@ -12,7 +12,7 @@ correct (the checker), another worker service dedicated to actually ingest the deposit into the swh archive. - - client: a python sčript `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 diff --git a/docs/specs/index.rst b/docs/specs/index.rst --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -1,13 +1,12 @@ .. _swh-deposit-specs: -Blueprint Specifications -========================= +Specifications +============== .. toctree:: :maxdepth: 1 :caption: Contents: - blueprint.rst spec-loading.rst protocol-reference.rst spec-meta-deposit.rst diff --git a/docs/tests/tests_HAL.rst b/docs/tests/tests_HAL.rst deleted file mode 100644 --- a/docs/tests/tests_HAL.rst +++ /dev/null @@ -1,67 +0,0 @@ -Tests scenarios for client -========================== - -Scenarios for HAL- on HAL's platform ------------------------------------- - -The same procedure is used for all tests: - -Software Author: - -#. prepare content -#. fill out form -#. submit - -HAL moderator: - -#. review content submitted -#. check metadata fields on HAL -#. validate submission - -SWH side: - -1. check content in SWH: - - - directory was created - - revision was created - - release was created when releaseNotes and softwareVersion was included (new feature!) - - origin corresponds to HAL url - -2. check metadata fields on SWH (in revision) -3. check directory -4. check swh-id on HAL -5. check browsability when entering SWH artifact from HAL -6. check vault artifact recreation -7. access deposit's origin from SWH - -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| scenario | test case | data | result | exceptions or specific checks | -+=============+===========================================+==========+=========+=========================================+ -| submit code | content: .tar.gz | .zip | success | | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| submit code | content: .zip | .tar.gz | success | | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| submit code | content: no content | empty | fail | blocked on HAL | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| submit code | content: double compression (.zip in .zip)| .zip x 2 | fail | status `failed` on SWH | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| submit code | all metadata-single entry | metadata | success | check that all metadata is transmitted | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| submit code | multiple entries | metadata | success | languages / authors / descriptions | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| new version | new content- same metadata | content | success | check new swh-id in SWH and HAL | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| new version | same content- new metadata | metadata | ? | dead angle- doesn't arrives to SWH | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| new version | new content-new metadata | C & M | success | check artifacts history in revisions | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ -| submit code | deposit on another hal platform | C & M | success | | -+-------------+-------------------------------------------+----------+---------+-----------------------------------------+ - -Past known bugs: - -- v2 problem, where swh-id from first version is kept in the second version - instead of the new swh-id. -- when deposit workers are down- error 500 is returned on HAL without real - explanation (because there is no error on SWH- deposit status - stays `deposited`).