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