docs: include the README file in the main index page

Convert README from markdown to ReST to make it embeddable in
docs/index.rst

README.md

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

README.rst

+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.

docs/index.rst

 .. _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

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",