diff --git a/README.md b/README.md
deleted file mode 100644
index 6cdd626..0000000
--- a/README.md
+++ /dev/null
@@ -1,6 +0,0 @@
-Software Heritage code scanner
-==============================
-
-Source code scanner using the
-[Software Heritage](https://www.softwareheritage.org/) [archive](https://archive.softwareheritage.org/)
-as knowledge base.
diff --git a/README.rst b/README.rst
new file mode 120000
index 0000000..cffceba
--- /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
index 0000000..426b3ee
--- /dev/null
+++ b/docs/README.rst
@@ -0,0 +1,26 @@
+Software Heritage - Code Scanner
+================================
+
+Source code scanner using the
+`Software Heritage` <https://www.softwareheritage.org/>_
+`archive <https://archive.softwareheritage.org/>`_
+as knowledge base.
+
+
+Sample usage
+------------
+
+.. code-block:: shell
+
+   $ swh scanner scan --help
+
+   Usage: swh scanner scan [OPTIONS] PATH
+
+   Scan a source code project to discover files and directories already
+   present in the archive
+
+   Options:
+     -u, --api-url API_URL     url for the api request  [default:
+			       https://archive.softwareheritage.org/api/1]
+     -f, --format [text|json]  select the output format
+     -h, --help                Show this message and exit.
diff --git a/docs/index.rst b/docs/index.rst
index b86a292..90a3290 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,19 +1,16 @@
 .. _swh-scanner:
 
-Software Heritage - code scanner
-================================
-
-Source code scanner using the Software Heritage archive as knowledge base.
+.. include:: README.rst
 
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
diff --git a/setup.py b/setup.py
index 5820bd1..78ab3c1 100755
--- a/setup.py
+++ b/setup.py
@@ -1,72 +1,72 @@
 #!/usr/bin/env python3
 # Copyright (C) 2019  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
 
 from setuptools import setup, find_packages
 
 from os import path
 from io import open
 
 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()
 
 
 def parse_requirements(name=None):
     if name:
         reqf = 'requirements-%s.txt' % name
     else:
         reqf = 'requirements.txt'
 
     requirements = []
     if not path.exists(reqf):
         return requirements
 
     with open(reqf) as f:
         for line in f.readlines():
             line = line.strip()
             if not line or line.startswith('#'):
                 continue
             requirements.append(line)
     return requirements
 
 
 # Edit this part to match your module.
 # Full sample:
 #   https://forge.softwareheritage.org/diffusion/DCORE/browse/master/setup.py
 setup(
     name='swh.scanner',
     description='Software Heritage code scanner',
     long_description=long_description,
-    long_description_content_type='text/markdown',
+    long_description_content_type='text/x-rst',
     author='Software Heritage developers',
     author_email='swh-devel@inria.fr',
     url='https://forge.softwareheritage.org/diffusion/DTSCN/',
     packages=find_packages(),  # packages's modules
     install_requires=parse_requirements() + parse_requirements('swh'),
     tests_require=parse_requirements('test'),
     setup_requires=['vcversioner'],
     extras_require={'testing': parse_requirements('test')},
     vcversioner={},
     include_package_data=True,
     entry_points='''
         [swh.cli.subcommands]
         scanner=swh.scanner.cli:scanner
     ''',
     classifiers=[
         "Programming Language :: Python :: 3",
         "Intended Audience :: Developers",
         "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
         "Operating System :: OS Independent",
         "Development Status :: 3 - Alpha",
     ],
     project_urls={
         'Bug Reports': 'https://forge.softwareheritage.org/maniphest',
         'Funding': 'https://www.softwareheritage.org/donate',
         'Source': 'https://forge.softwareheritage.org/source/swh-scanner',
     },
 )