docs: Unify READMEs in the documentation and the source code

README.md

-# 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

README.rst

+docs/README.rst
\ No newline at end of file

docs/README.rst

+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 <loader>` workers run by the SWH project from sourve code
+origins identified by :term:`lister <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 <persistent-identifiers>` 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
+<https://hal.archives-ouvertes.fr/hal-02446202>`_ (e.g. in a `scientific paper
+<https://www.softwareheritage.org/2020/05/26/citing-software-with-style/>`_) and
+retrieve it using the :ref:`vault <swh-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
+<https://archive.softwareheritage.org/save/>`_ 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/

docs/index.rst

 .. _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 <loader>` workers run by the SWH project
-from sourve code origins identified by :term:`lister <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
-<persistent-identifiers>` 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
-<https://hal.archives-ouvertes.fr/hal-02446202>`_ (e.g. in a `scientific paper
-<https://www.softwareheritage.org/2020/05/26/citing-software-with-style/>`_)
-and retrieve it using the :ref:`vault <swh-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
-<https://archive.softwareheritage.org/save/>`_ 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

setup.py

 #!/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 @@ from setuptools import find_packages, setup
 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()