diff --git a/README.md b/README.md deleted file mode 100644 --- a/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# swh-deposit - -This is [Software Heritage](https://www.softwareheritage.org)'s -[SWORD 2.0](http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html) Server -implementation, as well as a simple client to upload deposits on the server. - -**S.W.O.R.D** (**S**imple **W**eb-Service **O**ffering **R**epository -**D**eposit) is an interoperability standard for digital file deposit. - -This implementation will permit interaction between a client (a -repository) and a server (SWH repository) to permit deposits of -software source code archives and associated metadata. - -The documentation is at ./docs/README-specification.md diff --git a/README.rst b/README.rst new file mode 120000 --- /dev/null +++ b/README.rst @@ -0,0 +1 @@ +docs/README.rst \ No newline at end of file diff --git a/docs/README.rst b/docs/README.rst new file mode 100644 --- /dev/null +++ b/docs/README.rst @@ -0,0 +1,71 @@ +Software Heritage - Deposit +=========================== + +Simple Web-Service Offering Repository Deposit (S.W.O.R.D) is an interoperability +standard for digital file deposit. + +This repository is both the `SWORD v2`_ Server and a deposit command-line client +implementations. + +This implementation allows interaction between a client (a repository) and a server (SWH +repository) to deposit software source code archives and associated metadata. + +Description +----------- + +Most of the software source code artifacts present in the SWH Archive are gathered by +the mean of :term:`loader ` workers run by the SWH project from sourve code +origins identified by :term:`lister ` workers. This is a pull mechanism: it's +the responsibility of the SWH project to gather and collect source code artifacts that +way. + +Alternatively, SWH allows its partners to push source code artifacts and metadata +directly into the Archive with a push-based mechanism. By using this possibility +different actors, holding software artifacts or metadata, can preserve their assets +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`. + +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 +result of that is a :ref:`SWHID ` that can be used to uniquely +and persistently identify that very piece of source code. + +This unique identifier can then be used to `reference the source code +`_ (e.g. in a `scientific paper +`_) and +retrieve it using the :ref:`vault ` feature of the SWH Archive platform. + +The differences between a piece of code uploaded using the deposit rather than simply +asking SWH to archive a repository using the `save code now +`_ feature are: + +- a deposited artifact is provided from one of the SWH partners which is regarded as a + trusted authority, +- a deposited artifact requires metadata properties describing the source code artifact, +- a deposited artifact has a codemeta_ metadata entry attached to it, +- a deposited artifact has the same visibility on the SWH Archive than a collected + repository, +- a deposited artifact can be searched with its provided url property on the SWH + Archive, +- the deposit API uses the `SWORD v2`_ API, thus requires some tooling to send deposits + to SWH. These tools are provided with this repository. + +See the :ref:`user-manual` page for more details on how to use the deposit client +command line tools to push a deposit in the SWH Archive. + +See the :ref:`swh-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. + +See :ref:`swh-deposit-dev` 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 +`swh.deposit` stack. + + +.. _codemeta: https://codemeta.github.io/ +.. _`SWORD v2`: http://swordapp.org/sword-v2/ diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -1,77 +1,6 @@ .. _swh-deposit: -Software Heritage - Deposit -=========================== - -`SWORD v2`_ based deposit of software source code artifacts and metadata to the -Software Heritage (SWH) Archive. - -Description ------------ - -Most of the software source code artifacts present in the SWH Archive are -gathered by the mean of :term:`loader ` workers run by the SWH project -from sourve code origins identified by :term:`lister ` workers. This is -a pull mechanism: it's the responsibility of the SWH project to gather and -collect source code artifacts that way. - -Alternatively, SWH allows its partners to push source code -artifacts and metadata directly into the Archive with a push-based mechanism. -By using this possibility different actors, holding software artifacts or -metadata, can preserve their assets 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`. - -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 result of that is a :ref:`SWHID -` that can be used to uniquely and persistently -identify that very piece of source code. - -This unique identifier can then be used to `reference the source code -`_ (e.g. in a `scientific paper -`_) -and retrieve it using the :ref:`vault ` feature of the SWH Archive -platform. - -The differences between a piece of code uploaded using the deposit rather than -simply asking SWH to archive a repository using the `save code now -`_ feature are: - -- a deposited artifact is provided from one of the SWH partners which is - regarded as a trusted authority, -- a deposited artifact requires metadata properties describing the source code - artifact, -- a deposited artifact has a codemeta_ metadata entry attached to it, -- a deposited artifact has the same visibility on the SWH Archive than a - collected repository, -- a deposited artifacts can be searched with its provided url property on the - SWH Archive, -- the deposit API uses the `SWORD v2`_ API, thus requires some tooling to send - deposits to SWH. These tools are provided with this repository. - - -See the :ref:`user-manual` page for more details on how to use the deposit -client command line tools to push a deposit in the SWH Archive. - -See the :ref:`swh-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. - -See :ref:`swh-deposit-dev` 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 -`swh.deposit` stack. - - -.. _codemeta: https://codemeta.github.io/ -.. _`SWORD v2`: http://swordapp.org/sword-v2/ +.. include:: README.rst .. toctree:: :maxdepth: 2 diff --git a/setup.py b/setup.py --- a/setup.py +++ b/setup.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -# Copyright (C) 2015-2020 The Software Heritage developers +# Copyright (C) 2015-2021 The Software Heritage developers # See the AUTHORS file at the top-level directory of this distribution # License: GNU General Public License version 3, or any later version # See top-level LICENSE file for more information @@ -12,7 +12,7 @@ here = path.abspath(path.dirname(__file__)) # Get the long description from the README file -with open(path.join(here, "README.md"), encoding="utf-8") as f: +with open(path.join(here, "README.rst"), encoding="utf-8") as f: long_description = f.read()