From e3c59f8fa9c1f5ea8b5e1fc67c75d35cf79bde3b Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli Date: Tue, 5 Sep 2017 17:15:20 +0200 Subject: [PATCH] sanitize docstrings for sphinx --- swh/lister/core/abstractattribute.py | 14 +++++++----- swh/lister/core/indexing_lister.py | 34 +++++++++++++++------------- swh/lister/core/tasks.py | 12 ++++++---- 3 files changed, 33 insertions(+), 27 deletions(-) diff --git a/swh/lister/core/abstractattribute.py b/swh/lister/core/abstractattribute.py index afd244c..17db1a8 100644 --- a/swh/lister/core/abstractattribute.py +++ b/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 diff --git a/swh/lister/core/indexing_lister.py b/swh/lister/core/indexing_lister.py index 6d121c4..df8c31e 100644 --- a/swh/lister/core/indexing_lister.py +++ b/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 diff --git a/swh/lister/core/tasks.py b/swh/lister/core/tasks.py index 4ab610a..8a3a7a0 100644 --- a/swh/lister/core/tasks.py +++ b/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')