diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,12 +14,11 @@
 
 .. toctree::
    :maxdepth: 2
-   :caption: Overview:
    :titlesonly:
 
 
-   lister-tutorial
-   run-lister-tutorial
+   tutorial
+   run_a_new_lister
 
 
 Reference Documentation
diff --git a/swh/lister/cgit/lister.py b/swh/lister/cgit/lister.py
--- a/swh/lister/cgit/lister.py
+++ b/swh/lister/cgit/lister.py
@@ -33,19 +33,21 @@
     If several "Clone" urls are provided, prefer the http/https one, if
     any, otherwise fall bak to the first one.
 
-    A loader task is created for each git repository:
+    A loader task is created for each git repository::
 
-    Task:
-        Type: load-git
-        Policy: recurring
-        Args:
-            <git_clonable_url>
+        Task:
+            Type: load-git
+            Policy: recurring
+            Args:
+                <git_clonable_url>
 
-    Example:
-        Type: load-git
-        Policy: recurring
-        Args:
-            'https://git.savannah.gnu.org/git/elisp-es.git'
+    Example::
+
+        Task:
+            Type: load-git
+            Policy: recurring
+            Args:
+                'https://git.savannah.gnu.org/git/elisp-es.git'
     """
     MODEL = CGitModel
     DEFAULT_URL = 'https://git.savannah.gnu.org/cgit/'
diff --git a/swh/lister/core/lister_transports.py b/swh/lister/core/lister_transports.py
--- a/swh/lister/core/lister_transports.py
+++ b/swh/lister/core/lister_transports.py
@@ -57,25 +57,25 @@
         lister's instance name, which value is expected to be a list of
         credential structures (typically a couple username/password).
 
-        For example:
-
-        credentials:
-          github:  # github lister
-            github:  # has only one instance (so far)
-            - username: some
-              password: somekey
-            - username: one
-              password: onekey
-            - ...
-          gitlab:  # gitlab lister
-            riseup:  # has many instances
-            - username: someone
-              password: ...
-            - ...
-            gitlab:
-            - username: someone
-              password: ...
-            - ...
+        For example::
+
+            credentials:
+              github:  # github lister
+                github:  # has only one instance (so far)
+                  - username: some
+                    password: somekey
+                  - username: one
+                    password: onekey
+                  - ...
+                gitlab:  # gitlab lister
+                  riseup:  # has many instances
+                    - username: someone
+                      password: ...
+                    - ...
+                  gitlab:
+                    - username: someone
+                      password: ...
+                    - ...
 
         Returns:
             list of credential dicts for the current lister.
diff --git a/swh/lister/cran/lister.py b/swh/lister/cran/lister.py
--- a/swh/lister/cran/lister.py
+++ b/swh/lister/cran/lister.py
@@ -70,29 +70,20 @@
            containing data about the R packages.
 
         Returns:
-            List of Dict about r packages. For example:
-
-            .. code-block:: python
+            List of Dict about R packages. For example::
 
                 [
                     {
                         'Package': 'A3',
                         'Version': '1.0.0',
-                        'Title':
-                            'Accurate, Adaptable, and Accessible Error Metrics
-                             for Predictive\nModels',
-                        'Description':
-                            'Supplies tools for tabulating and analyzing the
-                             results of predictive models. The methods employed
-                             are ... '
+                        'Title': 'A3 package',
+                        'Description': ...
                     },
                     {
                         'Package': 'abbyyR',
                         'Version': '0.5.4',
-                        'Title':
-                            'Access to Abbyy OCR (OCR) API',
-                        'Description': 'Get text from images of text using
-                                        Abbyy Cloud Optical Character\n ...'
+                        'Title': 'Access to Abbyy OCR (OCR) API',
+                        'Description': ...'
                     },
                     ...
                 ]
diff --git a/swh/lister/gnu/lister.py b/swh/lister/gnu/lister.py
--- a/swh/lister/gnu/lister.py
+++ b/swh/lister/gnu/lister.py
@@ -77,16 +77,19 @@
             response: Unused
 
         Returns:
-            List of packages name, url, last modification time
+            List of packages name, url, last modification time::
 
-            .. code-block:: python
                 [
-                    {'name': '3dldf',
-                     'url': 'https://ftp.gnu.org/gnu/3dldf/',
-                     'time_modified': '2003-12-09T20:43:20+00:00'},
-                    {'name': '8sync',
-                     'url': 'https://ftp.gnu.org/gnu/8sync/',
-                     'time_modified': '2016-12-06T02:37:10+00:00'},
+                    {
+                        'name': '3dldf',
+                        'url': 'https://ftp.gnu.org/gnu/3dldf/',
+                        'time_modified': '2003-12-09T20:43:20+00:00'
+                    },
+                    {
+                        'name': '8sync',
+                        'url': 'https://ftp.gnu.org/gnu/8sync/',
+                        'time_modified': '2016-12-06T02:37:10+00:00'
+                    },
                     ...
                 ]
 
diff --git a/swh/lister/packagist/lister.py b/swh/lister/packagist/lister.py
--- a/swh/lister/packagist/lister.py
+++ b/swh/lister/packagist/lister.py
@@ -33,21 +33,23 @@
         variable `PAGE`, to receive a list of all the package names
         present in the Packagist package manager. Iterates over all the
         packages and constructs the metadata url of the package from
-        the name of the package and creates a loading task.
-
-        Task:
-            Type: load-packagist
-            Policy: recurring
-            Args:
-                <package_name>
-                <package_metadata_url>
-
-        Example:
-            Type: load-packagist
-            Policy: recurring
-            Args:
-                'hypejunction/hypegamemechanics'
-                'https://repo.packagist.org/p/hypejunction/hypegamemechanics.json'
+        the name of the package and creates a loading task::
+
+            Task:
+                Type: load-packagist
+                Policy: recurring
+                Args:
+                    <package_name>
+                    <package_metadata_url>
+
+        Example::
+
+            Task:
+                Type: load-packagist
+                Policy: recurring
+                Args:
+                    'hypejunction/hypegamemechanics'
+                    'https://repo.packagist.org/p/hypejunction/hypegamemechanics.json'
 
     """
     MODEL = PackagistModel