sanitize docstrings for sphinx

swh/lister/core/abstractattribute.py

@@ -6,16 +6,18 @@
 class AbstractAttribute:
     """AbstractAttributes in a base class must be overridden by the subclass.
 
-    It's like the @abc.abstractmethod decorator, but for things that are
-        explicitly attributes/properties, not methods, without the need for
-        empty method def boilerplate. Like abc.abstractmethod, the class
-        containing AbstractAttributes must inherit abc.ABC or use the
-        abc.ABCMeta metaclass.
+    It's like the :py:func:`abc.abstractmethod` decorator, but for things that
+    are explicitly attributes/properties, not methods, without the need for
+    empty method def boilerplate. Like abc.abstractmethod, the class containing
+    AbstractAttributes must inherit from :py:class:`abc.ABC` or use the
+    :py:class:`abc.ABCMeta` metaclass.
+
+    Usage example::
 
-    Usage Example:
         import abc
         class ClassContainingAnAbstractAttribute(abc.ABC):
             foo = AbstractAttribute('descriptive docstring for foo')
+
     """
     __isabstractmethod__ = True
 

swh/lister/core/indexing_lister.py

@@ -13,22 +13,22 @@ from .lister_base import SWHListerBase
 
 class SWHIndexingLister(SWHListerBase):
     """Lister* intermediate class for any service that follows the pattern:
-        -- The service must report at least one stable unique identifier,
-            known herein as the UID value, for every listed repository.
-        -- If the service splits the list of repositories into sublists,
-            it must report at least one stable and sorted index identifier
-            for every listed repository, known herein as the indexable value,
-            which can be used as part of the service endpoint query to request
-            a sublist beginning from that index. This might be the UID if the
-            UID is monotonic.
-        -- Client sends a request to list repositories starting from a given
-            index.
-        -- Client receives structured (json/xml/etc) response with information
-            about a sequential series of repositories starting from that index
-            and, if necessary/available, some indication of the URL or index
-            for fetching the next series of repository data.
 
-        * - See swh.lister.core.lister_base.SWHListerBase for more details.
+    - The service must report at least one stable unique identifier, known
+      herein as the UID value, for every listed repository.
+    - If the service splits the list of repositories into sublists, it must
+      report at least one stable and sorted index identifier for every listed
+      repository, known herein as the indexable value, which can be used as
+      part of the service endpoint query to request a sublist beginning from
+      that index. This might be the UID if the UID is monotonic.
+    - Client sends a request to list repositories starting from a given
+      index.
+    - Client receives structured (json/xml/etc) response with information about
+      a sequential series of repositories starting from that index and, if
+      necessary/available, some indication of the URL or index for fetching the
+      next series of repository data.
+
+    See :py:class:`swh.lister.core.lister_base.SWHListerBase` for more details.
 
     This class cannot be instantiated. To create a new Lister for a source
     code listing service that follows the model described above, you must
@@ -36,8 +36,10 @@ class SWHIndexingLister(SWHListerBase):
     any unmet implementation/override requirements of this class's base.
     (see parent class and member docstrings for details)
 
-    Required Overrides:
+    Required Overrides::
+
         def get_next_target_from_response
+
     """
 
     @abc.abstractmethod

swh/lister/core/tasks.py

@@ -24,16 +24,18 @@ class ListerTaskBase(Task, metaclass=AbstractTaskMeta):
 
         There are two main kinds of lister tasks:
 
-            1) Discovering new repositories.
-            2) Refreshing the list of already discovered repositories.
+        1. Discovering new repositories.
+        2. Refreshing the list of already discovered repositories.
 
         If the hosting service is indexable (according to the requirements of
-        SWHIndexingLister), then we can optionally partition the set of known
-        repositories into sub-sets to distribute the work.
+        :py:class:`SWHIndexingLister`), then we can optionally partition the
+        set of known repositories into sub-sets to distribute the work.
 
         This means that there is a third possible Task type for Indexing
         Listers:
-            3) Discover or refresh a specific range of indices.
+
+        3. Discover or refresh a specific range of indices.
+
     """
     task_queue = AbstractAttribute('Celery Task queue name')