diff --git a/README.md b/README.md
deleted file mode 100644
index e8ca35ae659a2d74c9c3b7cbee0801443c689562..0000000000000000000000000000000000000000
--- a/README.md
+++ /dev/null
@@ -1,107 +0,0 @@
-swh-lister
-==========
-
-This component from the Software Heritage stack aims to produce listings
-of software origins and their urls hosted on various public developer platforms
-or package managers. As these operations are quite similar, it provides a set of
-Python modules abstracting common software origins listing behaviors.
-
-It also provides several lister implementations, contained in the
-following Python modules:
-
-- `swh.lister.bitbucket`
-- `swh.lister.cgit`
-- `swh.lister.cran`
-- `swh.lister.debian`
-- `swh.lister.gitea`
-- `swh.lister.github`
-- `swh.lister.gitlab`
-- `swh.lister.gnu`
-- `swh.lister.gogs`
-- `swh.lister.golang`
-- `swh.lister.hex`
-- `swh.lister.launchpad`
-- `swh.lister.maven`
-- `swh.lister.npm`
-- `swh.lister.packagist`
-- `swh.lister.phabricator`
-- `swh.lister.pypi`
-- `swh.lister.rpm`
-- `swh.lister.tuleap`
-- `swh.lister.bioconductor`
-
-Dependencies
-------------
-
-All required dependencies can be found in the `requirements*.txt` files located
-at the root of the repository.
-
-Local deployment
-----------------
-
-## lister configuration
-
-Each lister implemented so far by Software Heritage (`bitbucket`, `cgit`, `cran`, `debian`,
-`gitea`, `github`, `gitlab`, `gnu`, `golang`, `launchpad`, `npm`, `packagist`, `phabricator`, `pypi`, `tuleap`, `maven`)
-must be configured by following the instructions below (please note that you have to replace
-`<lister_name>` by one of the lister name introduced above).
-
-### Preparation steps
-
-1. `mkdir ~/.config/swh/`
-2. create configuration file `~/.config/swh/listers.yml`
-
-### Configuration file sample
-
-Minimalistic configuration shared by all listers to add in file `~/.config/swh/listers.yml`:
-
-```yaml
-scheduler:
- cls: 'remote'
- args:
- url: 'http://localhost:5008/'
-
-credentials: {}
-```
-
-Note: This expects scheduler (5008) service to run locally
-
-## Executing a lister
-
-Once configured, a lister can be executed by using the `swh` CLI tool with the
-following options and commands:
-
-```
-$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister <lister_name> [lister_parameters]
-```
-
-Examples:
-
-```
-$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister bitbucket
-
-$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister cran
-
-$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister gitea url=https://codeberg.org/api/v1/
-
-$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister gitlab url=https://salsa.debian.org/api/v4/
-
-$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister npm
-
-$ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister pypi
-```
-
-Licensing
----------
-
-This program is free software: you can redistribute it and/or modify it under
-the terms of the GNU General Public License as published by the Free Software
-Foundation, either version 3 of the License, or (at your option) any later
-version.
-
-This program is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-See top-level LICENSE file for the full text of the GNU General Public License
-along with this program.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1d89aa60bc3a843e66e3058b0fc544eb0e24e437
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,122 @@
+Software Heritage - Listers
+===========================
+
+Collection of listers for source code distribution places like development
+forges, FOSS distributions, package managers, etc. Each lister is in charge to
+enumerate the software origins (e.g., VCS, packages, etc.) available at a
+source code distribution place.
+
+A lister is a component from the Software Heritage stack aims to produce
+listings of software origins and their urls hosted on various public developer
+platforms or package managers. As these operations are quite similar, this
+package provides a set of Python modules abstracting common software origins
+listing behaviors.
+
+It also provides several lister implementations, contained in the
+following Python modules:
+
+- ``swh.lister.bitbucket``
+- ``swh.lister.cgit``
+- ``swh.lister.cran``
+- ``swh.lister.debian``
+- ``swh.lister.gitea``
+- ``swh.lister.github``
+- ``swh.lister.gitlab``
+- ``swh.lister.gnu``
+- ``swh.lister.gogs``
+- ``swh.lister.golang``
+- ``swh.lister.hex``
+- ``swh.lister.launchpad``
+- ``swh.lister.maven``
+- ``swh.lister.npm``
+- ``swh.lister.packagist``
+- ``swh.lister.phabricator``
+- ``swh.lister.pypi``
+- ``swh.lister.rpm``
+- ``swh.lister.tuleap``
+- ``swh.lister.bioconductor``
+
+Dependencies
+------------
+
+All required dependencies can be found in the ``requirements*.txt`` files
+located at the root of the repository.
+
+Local deployment
+----------------
+
+Lister configuration
+++++++++++++++++++++
+
+Each lister implemented so far by Software Heritage (``bitbucket``, ``cgit``,
+``cran``, ``debian``, ``gitea``, ``github``, ``gitlab``, ``gnu``, ``golang``,
+``launchpad``, ``npm``, ``packagist``, ``phabricator``, ``pypi``, ``tuleap``,
+``maven``) must be configured by following the instructions below (please note
+that you have to replace ``<lister_name>`` by one of the lister name introduced
+above).
+
+Preparation steps
+~~~~~~~~~~~~~~~~~
+
+1. ``mkdir ~/.config/swh/``
+2. create configuration file ``~/.config/swh/listers.yml``
+
+Configuration file sample
++++++++++++++++++++++++++
+
+Minimalistic configuration shared by all listers to add in file
+``~/.config/swh/listers.yml``:
+
+.. code-block:: yaml
+
+ scheduler:
+ cls: 'remote'
+ args:
+ url: 'http://localhost:5008/'
+
+ credentials: {}
+
+Note: This expects scheduler (5008) service to run locally
+
+Executing a lister
+------------------
+
+Once configured, a lister can be executed by using the ``swh`` CLI tool with
+the following options and commands:
+
+.. code-block:: shell
+
+ $ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister <lister_name> [lister_parameters]
+
+
+Examples:
+
+.. code-block:: shell
+
+ $ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister bitbucket
+
+ $ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister cran
+
+ $ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister gitea url=https://codeberg.org/api/v1/
+
+ $ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister gitlab url=https://salsa.debian.org/api/v4/
+
+ $ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister npm
+
+ $ swh --log-level DEBUG lister -C ~/.config/swh/listers.yml run --lister pypi
+
+
+Licensing
+---------
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+See top-level LICENSE file for the full text of the GNU General Public License
+along with this program.
diff --git a/docs/index.rst b/docs/index.rst
index 846bbdb333245d5a6bb8fda6ba66b330bb73c7cf..e93669b28a566bd3626f7ab233e5a14b69450509 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,12 +1,6 @@
.. _swh-lister:
-Software Heritage - Listers
-===========================
-
-Collection of listers for source code distribution places like development
-forges, FOSS distributions, package managers, etc. Each lister is in charge to
-enumerate the software origins (e.g., VCS, packages, etc.) available at a
-source code distribution place.
+.. include:: README.rst
Overview
@@ -16,7 +10,6 @@ Overview
:maxdepth: 2
:titlesonly:
-
tutorial
run_a_new_lister
save_forge
diff --git a/setup.py b/setup.py
index 2a9c51f61c5611d0a4e78cfbae5890cedf5f7016..cb4b008fe9b7d6add0eea9562cdce47c940e9f88 100755
--- a/setup.py
+++ b/setup.py
@@ -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()
@@ -39,7 +39,7 @@ setup(
name="swh.lister",
description="Software Heritage lister",
long_description=long_description,
- long_description_content_type="text/markdown",
+ long_description_content_type="text/x-rst",
python_requires=">=3.7",
author="Software Heritage developers",
author_email="swh-devel@inria.fr",