Minor docstring fixes: links and formatting

Author: vshlapakov

scrapinghub/client/__init__.py

@@ -70,9 +70,9 @@ def get_project(self, project_id):
         return self.projects.get(parse_project_id(project_id))
 
     def get_job(self, job_key):
-        """Get Job with a given job key.
+        """Get :class:`~scrapinghub.client.jobs.Job` with a given job key.
 
-        :param job_key: job key string in format 'project_id/spider_id/job_id',
+        :param job_key: job key string in format ``project_id/spider_id/job_id``,
             where all the components are integers.
         :return: a job instance.
         :rtype: :class:`~scrapinghub.client.jobs.Job`

scrapinghub/client/collections.py

@@ -27,7 +27,7 @@ class Collections(_Proxy, _DownloadableProxyMixin):
     def get(self, type_, name):
         """Base method to get a collection with a given type and name.
 
-        :param type_: a collection type string.
+        :param `type_`: a collection type string.
         :param name: a collection name string.
         :return: a collection object.
         :rtype: :class:`Collection`
@@ -248,7 +248,7 @@ def create_writer(self, start=0, auth=None, size=1000, interval=15,
         :param maxitemsize: (optional) max item size in bytes.
         :param callback: (optional) some callback function.
         :return: a new writer object.
-        :rtype: :class:`~scrapinghub.hubstorage.batchuploader._BatchWriter`
+        :rtype: :class:`scrapinghub.hubstorage.batchuploader._BatchWriter`
 
         If provided - calllback shouldn't try to inject more items in the queue,
         otherwise it can lead to deadlocks.

scrapinghub/client/frontiers.py

@@ -113,11 +113,7 @@ def list(self):
 
     @property
     def newcount(self):
-        """Amount of new entries added to all frontiers.
-
-        :return: amount of new entries.
-        :rtype: :class:`int`
-        """
+        """Integer amount of new entries added to all frontiers."""
         return sum(self._origin.newcount.values())
 
     def flush(self):
@@ -199,11 +195,7 @@ def flush(self):
 
     @property
     def newcount(self):
-        """Amount of new entries added to frontier.
-
-        :return: amount of new entries.
-        :rtype: :class:`int`
-        """
+        """Integer amount of new entries added to frontier."""
         newcount_values = self._frontiers._origin.newcount
         return sum(v for (frontier, _), v in newcount_values.items()
                    if frontier == self.key)
@@ -298,16 +290,13 @@ def flush(self):
 
     @property
     def newcount(self):
-        """Amount of new entries added to slot.
-
-        :return: amount of new entries.
-        :rtype: :class:`int`
-        """
+        """Integer amount of new entries added to slot."""
         newcount_values = self._frontier._frontiers._origin.newcount
         return newcount_values.get((self._frontier.key, self.key), 0)
 
 
 class FrontierSlotFingerprints(object):
+    """Representation of request fingerprints collection stored in slot."""
 
     def __init__(self, slot):
         self.key = slot.key
@@ -350,6 +339,7 @@ def list(self, **params):
 
 
 class FrontierSlotQueue(object):
+    """Representation of request batches queue stored in slot."""
 
     def __init__(self, slot):
         self.key = slot.key

scrapinghub/client/items.py

@@ -6,9 +6,9 @@
 class Items(_ItemsResourceProxy, _DownloadableProxyMixin):
     """Representation of collection of job items.
 
-    Not a public constructor: use :class:`~scrapinghub.client.jobs.Job` instanc
-    e to get a :class:`Items` instance.
-    See :attr:`~scrapinghub.client.jobs.Job.items` attribute.
+    Not a public constructor: use :class:`~scrapinghub.client.jobs.Job`
+    instance to get a :class:`Items` instance. See
+    :attr:`~scrapinghub.client.jobs.Job.items` attribute.
 
     Please note that :meth:`list` method can use a lot of memory and for
     a large amount of logs it's recommended to iterate through it via

scrapinghub/client/jobs.py

@@ -24,7 +24,7 @@ class Jobs(object):
     and :attr:`scrapinghub.client.spiders.Spider.jobs` attributes.
 
     :ivar project_id: a string project id.
-    :ivar spider: :class:`Spider` object if defined.
+    :ivar spider: :class:`~scrapinghub.client.spiders.Spider` object if defined.
 
     Usage::
 
@@ -112,16 +112,16 @@ def iter(self, count=None, start=None, spider=None, state=None,
             >>> [job['key'] for job in jobs_summary]
             ['123/1/3', '123/1/2', '123/1/1']
 
-        - job summary fieldset is less detailed than job.metadata but contains
-            few new fields as well. Additional fields can be requested using
-            ``meta`` parameter. If it's used, then it's up to the user to list
-            all the required fields, so only few default fields would be added
-            except requested ones::
+        - job summary fieldset is less detailed than :class:`JobMeta` but
+          contains a few new fields as well. Additional fields can be requested
+          using ``meta`` parameter. If it's used, then it's up to the user to
+          list all the required fields, so only few default fields would be
+          added except requested ones::
 
             >>> jobs_summary = project.jobs.iter(meta=['scheduled_by', ])
 
         - by default :meth:`Jobs.iter` returns maximum last 1000 results.
-            Pagination is available using start parameter::
+          Pagination is available using start parameter::
 
             >>> jobs_summary = spider.jobs.iter(start=1000)
 
@@ -227,13 +227,14 @@ def run(self, spider=None, units=None, priority=None, meta=None,
         return Job(self._client, response['jobid'])
 
     def get(self, job_key):
-        """Get a Job with a given job_key.
+        """Get a :class:`Job` with a given job_key.
 
         :param job_key: a string job key.
 
         job_key's project component should match the project used to get
         :class:`Jobs` instance, and job_key's spider component should match
-        the spider (if :attr:`Spider.jobs` was used).
+        the spider (if :class:`~scrapinghub.client.spiders.Spider` was used
+        to get :class:`Jobs` instance).
 
         :return: a job object.
         :rtype: :class:`Job`
@@ -509,7 +510,7 @@ class JobMeta(_MappingProxy):
     """Class representing job metadata.
 
     Not a public constructor: use :class:`Job` instance to get a
-    :class:`JobMeta` instance. See :attr:`Job.metadata` attribute.
+    :class:`JobMeta` instance. See :attr:`~Job.metadata` attribute.
 
     Usage:
 

scrapinghub/client/logs.py

@@ -54,7 +54,7 @@ def log(self, message, level=logging.INFO, ts=None, **other):
 
         :param message: a string message.
         :param level: (optional) logging level, default to INFO.
-        :param ts: (optional) unix timestamp in milliseconds.
+        :param ts: (optional) UNIX timestamp in milliseconds.
         :param \*\*other: other optional kwargs.
         """
         self._origin.log(message, level=level, ts=ts, **other)

scrapinghub/client/requests.py

@@ -50,7 +50,7 @@ def add(self, url, status, method, rs, parent, duration, ts, fp=None):
         :param rs: response body length.
         :param parent: parent request id or ``None``.
         :param duration: request duration in milliseconds.
-        :param ts: unix timestamp in milliseconds.
+        :param ts: UNIX timestamp in milliseconds.
         :param fp: (optional) string fingerprint for the request.
         """
         return self._origin.add(