diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,9 @@
+swh-scanner
+===========
+
+Source code scanner to analyze code bases and compare them with source code
+artifacts archived by Software Heritage
+
+See the
+[documentation](https://docs.softwareheritage.org/devel/swh-scanner/index.html)
+for more details.
\ No newline at end of file
diff --git a/README.rst b/README.rst
deleted file mode 120000
--- a/README.rst
+++ /dev/null
@@ -1 +0,0 @@
-docs/README.rst
\ No newline at end of file
diff --git a/docs/README.rst b/docs/README.rst
deleted file mode 100644
--- a/docs/README.rst
+++ /dev/null
@@ -1,26 +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.
-
-
-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/cli.rst b/docs/cli.rst
new file mode 100644
--- /dev/null
+++ b/docs/cli.rst
@@ -0,0 +1,6 @@
+Command-line interface
+======================
+
+.. click:: swh.scanner.cli:scan
+  :prog: swh scanner scan
+  :show-nested:
diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,16 +1,17 @@
 .. _swh-scanner:
 
-.. include:: README.rst
+Software Heritage - Code Scanner
+================================
+
+Source code scanner using the
+`Software Heritage <https://www.softwareheritage.org/>`_
+`archive <https://archive.softwareheritage.org/>`_
+as knowledge base.
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   cli
+   /apidoc/swh.scanner
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -12,7 +12,7 @@
 here = path.abspath(path.dirname(__file__))
 
 # Get the long description from the README file
-with open(path.join(here, "README.rst"), encoding="utf-8") as f:
+with open(path.join(here, "README.md"), encoding="utf-8") as f:
     long_description = f.read()
 
 
@@ -42,7 +42,7 @@
     name="swh.scanner",
     description="Software Heritage code scanner",
     long_description=long_description,
-    long_description_content_type="text/x-rst",
+    long_description_content_type="text/markdown",
     python_requires=">=3.7",
     author="Software Heritage developers",
     author_email="swh-devel@inria.fr",
diff --git a/swh/scanner/cli.py b/swh/scanner/cli.py
--- a/swh/scanner/cli.py
+++ b/swh/scanner/cli.py
@@ -62,7 +62,7 @@
     default="https://archive.softwareheritage.org/api/1",
     metavar="API_URL",
     show_default=True,
-    help="url for the api request",
+    help="URL for the api request",
 )
 @click.option(
     "--exclude",
@@ -70,17 +70,19 @@
     "patterns",
     metavar="PATTERN",
     multiple=True,
-    help="recursively exclude a specific pattern",
+    help="Exclude directories using glob patterns \
+    (e.g., '*.git' to exclude all .git directories)",
 )
 @click.option(
     "-f",
     "--format",
-    type=click.Choice(["text", "json", "ndjson", "sunburst"], case_sensitive=False),
     default="text",
-    help="select the output format",
+    show_default=True,
+    type=click.Choice(["text", "json", "ndjson", "sunburst"], case_sensitive=False),
+    help="The output format",
 )
 @click.option(
-    "-i", "--interactive", is_flag=True, help="show the result in a dashboard"
+    "-i", "--interactive", is_flag=True, help="Show the result in a dashboard"
 )
 @click.pass_context
 def scan(ctx, root_path, api_url, patterns, format, interactive):