diff --git a/README.rst b/README.rst
index d46ade8..cffceba 120000
--- a/README.rst
+++ b/README.rst
@@ -1 +1 @@
-docs/index.rst
\ No newline at end of file
+docs/README.rst
\ No newline at end of file
diff --git a/docs/index.rst b/docs/README.rst
similarity index 88%
copy from docs/index.rst
copy to docs/README.rst
index 0b7aa8b..68397f4 100644
--- a/docs/index.rst
+++ b/docs/README.rst
@@ -1,37 +1,26 @@
-.. _swh-web-client:
-
 Software Heritage - Web client
 ==============================
 
 Client for Software Heritage Web applications, via their APIs.
 
 
 Sample usage
 ------------
 
 .. code-block:: python
 
    from swh.web.client import WebAPIClient
    cli = WebAPIClient()
 
    # retrieve any archived object via its PID
    cli.get('swh:1:rev:aafb16d69fd30ff58afdd69036a26047f3aebdc6')
 
    # same, but for specific object types
    cli.revision('swh:1:rev:aafb16d69fd30ff58afdd69036a26047f3aebdc6')
 
    # get() always retrieve entire objects, following pagination
    # WARNING: this might *not* be what you want for large objects
    cli.get('swh:1:snp:6a3a2cf0b2b90ce7ae1cf0a221ed68035b686f5a')
 
    # type-specific methods support explicit iteration through pages
    next(cli.snapshot('swh:1:snp:cabcc7d7bf639bbe1cc3b41989e1806618dd5764'))
-
-
-API Reference
--------------
-
-.. toctree::
-   :maxdepth: 2
-
-   /apidoc/swh.web.client
diff --git a/docs/index.rst b/docs/index.rst
index 0b7aa8b..fd1178f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,37 +1,12 @@
 .. _swh-web-client:
 
-Software Heritage - Web client
-==============================
-
-Client for Software Heritage Web applications, via their APIs.
-
-
-Sample usage
-------------
-
-.. code-block:: python
-
-   from swh.web.client import WebAPIClient
-   cli = WebAPIClient()
-
-   # retrieve any archived object via its PID
-   cli.get('swh:1:rev:aafb16d69fd30ff58afdd69036a26047f3aebdc6')
-
-   # same, but for specific object types
-   cli.revision('swh:1:rev:aafb16d69fd30ff58afdd69036a26047f3aebdc6')
-
-   # get() always retrieve entire objects, following pagination
-   # WARNING: this might *not* be what you want for large objects
-   cli.get('swh:1:snp:6a3a2cf0b2b90ce7ae1cf0a221ed68035b686f5a')
-
-   # type-specific methods support explicit iteration through pages
-   next(cli.snapshot('swh:1:snp:cabcc7d7bf639bbe1cc3b41989e1806618dd5764'))
+.. include:: README.rst
 
 
 API Reference
 -------------
 
 .. toctree::
    :maxdepth: 2
 
    /apidoc/swh.web.client