diff --git a/docs/extrinsic-metadata-specification.rst b/docs/extrinsic-metadata-specification.rst
--- a/docs/extrinsic-metadata-specification.rst
+++ b/docs/extrinsic-metadata-specification.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _extrinsic-metadata-specification:
 
 Extrinsic metadata specification
@@ -29,14 +31,13 @@
 
 An authority is uniquely defined by these properties:
 
-* its type, representing the kind of authority, which is one of these values:
+  * its type, representing the kind of authority, which is one of these values:
   * `deposit`, for metadata pushed to Software Heritage at the same time
     as a software artifact
   * `forge`, for metadata pulled from the same source as the one hosting
     the software artifacts (which includes package managers)
   * `registry`, for metadata pulled from a third-party
-
-* its URL, which unambiguously identifies an instance of the authority type.
+  * its URL, which unambiguously identifies an instance of the authority type.
 
 Examples:
 
diff --git a/swh/storage/algos/diff.py b/swh/storage/algos/diff.py
--- a/swh/storage/algos/diff.py
+++ b/swh/storage/algos/diff.py
@@ -248,6 +248,7 @@
     """
     Compare paths in lexicographic depth-first order.
     For instance, it returns:
+
         - "a" < "b"
         - "b/c/d" < "b"
         - "c/foo.txt" < "c.txt"
diff --git a/swh/storage/buffer.py b/swh/storage/buffer.py
--- a/swh/storage/buffer.py
+++ b/swh/storage/buffer.py
@@ -63,11 +63,12 @@
         """Enqueue contents to write to the storage.
 
         Following policies apply:
-        - First, check if the queue's threshold is hit. If it is flush content
-          to the storage.
 
-        - If not, check if the total size of enqueued contents's threshold is
-          hit. If it is flush content to the storage.
+            - First, check if the queue's threshold is hit.
+              If it is flush content to the storage.
+
+            - If not, check if the total size of enqueued contents's
+              threshold is hit. If it is flush content to the storage.
 
         """
         s = self.object_add(content, object_type='content')
diff --git a/swh/storage/in_memory.py b/swh/storage/in_memory.py
--- a/swh/storage/in_memory.py
+++ b/swh/storage/in_memory.py
@@ -1436,13 +1436,13 @@
         Args:
             visits: iterable of dicts with keys:
 
-                origin: origin url
-                visit: origin visit id
-                type: type of loader used for the visit
-                date: timestamp of such visit
-                status: Visit's new status
-                metadata: Data associated to the visit
-                snapshot (sha1_git): identifier of the snapshot to add to
+                - **origin**: origin url
+                - **visit**: origin visit id
+                - **type**: type of loader used for the visit
+                - **date**: timestamp of such visit
+                - **status**: Visit's new status
+                - **metadata**: Data associated to the visit
+                - **snapshot**: identifier of the snapshot to add to
                     the visit
         """
         for visit in visits:
@@ -1558,16 +1558,17 @@
                 have successfully run to completion.
             require_snapshot (bool): If True, only a visit with a snapshot
                 will be returned.
+
         Returns:
             dict: a dict with the following keys:
 
-                origin: the URL of the origin
-                visit: origin visit id
-                type: type of loader used for the visit
-                date: timestamp of such visit
-                status: Visit's new status
-                metadata: Data associated to the visit
-                snapshot (Optional[sha1_git]): identifier of the snapshot
+                - **origin**: the URL of the origin
+                - **visit**: origin visit id
+                - **type**: type of loader used for the visit
+                - **date**: timestamp of such visit
+                - **status**: Visit's new status
+                - **metadata**: Data associated to the visit
+                - **snapshot** (Optional[sha1_git]): identifier of the snapshot
                     associated to the visit
         """
         origin = self._origins.get(origin)
diff --git a/swh/storage/storage.py b/swh/storage/storage.py
--- a/swh/storage/storage.py
+++ b/swh/storage/storage.py
@@ -1483,12 +1483,12 @@
         Args:
             visits: iterable of dicts with keys:
 
-                origin: dict with keys either `id` or `url`
-                visit: origin visit id
-                date: timestamp of such visit
-                status: Visit's new status
-                metadata: Data associated to the visit
-                snapshot (sha1_git): identifier of the snapshot to add to
+                - **origin**: dict with keys either `id` or `url`
+                - **visit**: origin visit id
+                - **date**: timestamp of such visit
+                - **status**: Visit's new status
+                - **metadata**: Data associated to the visit
+                - **snapshot**: identifier of the snapshot to add to
                     the visit
         """
         visits = copy.deepcopy(visits)
@@ -1588,16 +1588,17 @@
                 have successfully run to completion.
             require_snapshot (bool): If True, only a visit with a snapshot
                 will be returned.
+
         Returns:
             dict: a dict with the following keys:
 
-                origin: the URL of the origin
-                visit: origin visit id
-                type: type of loader used for the visit
-                date: timestamp of such visit
-                status: Visit's new status
-                metadata: Data associated to the visit
-                snapshot (Optional[sha1_git]): identifier of the snapshot
+                - **origin**: the URL of the origin
+                - **visit**: origin visit id
+                - **type**: type of loader used for the visit
+                - **date**: timestamp of such visit
+                - **status**: Visit's new status
+                - **metadata**: Data associated to the visit
+                - **snapshot** (Optional[sha1_git]): identifier of the snapshot
                     associated to the visit
         """
         origin_visit = db.origin_visit_get_latest(