Refactor and minor fixes for overview

Author: vshlapakov

docs/client/overview.rst

@@ -136,12 +136,12 @@ Use ``run`` method to run a new job for project/spider::
 
 Scheduling logic supports different options, like
 
-- job_args to provide arguments for the job
-- units to specify amount of units to run the job
-- job_settings to pass additional settings for the job
-- priority to set higher/lower priority of the job
-- add_tag to create a job with a set of initial tags
-- meta to pass additional custom metadata
+- **job_args** to provide arguments for the job
+- **units** to specify amount of units to run the job
+- **job_settings** to pass additional settings for the job
+- **priority** to set higher/lower priority of the job
+- **add_tag** to create a job with a set of initial tags
+- **meta** to pass additional custom metadata
 
 For example, to run a new job for a given spider with custom params::
 
@@ -211,8 +211,9 @@ To get jobs filtered by tags::
 
     >>> jobs_summary = project.jobs.iter(has_tag=['new', 'verified'], lacks_tag='obsolete')
 
-List of tags has ``OR`` power, so in the case above jobs with 'new' or
-'verified' tag are expected.
+List of tags in **has_tag** has ``OR`` power, so in the case above jobs with
+``new`` or ``verified`` tag are expected (while list of tags in **lacks_tag**
+has ``AND`` power).
 
 To get certain number of last finished jobs per some spider::
 
@@ -227,7 +228,7 @@ for filtering by state:
 - deleted
 
 Dict entries returned by ``iter`` method contain some additional meta,
-but can be easily converted to ``Job`` instances with::
+but can be easily converted to :class:`~scrapinghub.client.jobs.Job` instances with::
 
     >>> [Job(x['key']) for x in jobs]
     [
@@ -266,6 +267,25 @@ It's also possible to get last jobs summary (for each spider)::
 
 Note that there can be a lot of spiders, so the method above returns an iterator.
 
+
+update_tags
+^^^^^^^^^^^
+
+Tags is a convenient way to mark specific jobs (for better search, postprocessing etc).
+
+
+To mark all spider jobs with tag ``consumed``::
+
+    >>> spider.jobs.update_tags(add=['consumed'])
+
+To remove existing tag ``existing`` for all spider jobs::
+
+    >>> spider.jobs.update_tags(remove=['existing'])
+
+Modifying tags is available on :class:`~scrapinghub.client.spiders.Spider`/
+:class:`~scrapinghub.client.jobs.Job` levels.
+
+
 Job
 ---
 
@@ -286,6 +306,10 @@ To delete a job::
 
     >>> job.delete()
 
+To mark a job with tag ``consumed``::
+
+    >>> job.update_tags(add=['consumed'])
+
 .. _job-metadata:
 
 Metadata
@@ -404,31 +428,6 @@ Or post multiple events at once::
     >>> project.activity.add(events)
 
 
-Settings
---------
-
-You can work with project settings via :class:`~scrapinghub.client.projects.Settings`.
-
-To get a list of the project settings::
-
-    >>> project.settings.list()
-    [(u'default_job_units', 2), (u'job_runtime_limit', 24)]]
-
-To get a project setting value by name::
-
-    >>> project.settings.get('job_runtime_limit')
-    24
-
-To update a project setting value by name::
-
-    >>> project.settings.set('job_runtime_limit', 20)
-
-Or update a few project settings at once::
-
-    >>> project.settings.update({'default_job_units': 1,
-    ...                          'job_runtime_limit': 20})
-
-
 Collections
 -----------
 
@@ -559,24 +558,30 @@ Frontiers are available on project level only.
 
 .. _job-tags:
 
-Tags
-----
 
-Tags is a convenient way to mark specific jobs (for better search, postprocessing etc).
+Settings
+--------
 
-To mark a job with tag ``consumed``::
+You can work with project settings via :class:`~scrapinghub.client.projects.Settings`.
 
-    >>> job.update_tags(add=['consumed'])
+To get a list of the project settings::
 
-To mark all spider jobs with tag ``consumed``::
+    >>> project.settings.list()
+    [(u'default_job_units', 2), (u'job_runtime_limit', 24)]]
 
-    >>> spider.jobs.update_tags(add=['consumed'])
+To get a project setting value by name::
 
-To remove existing tag ``existing`` for all spider jobs::
+    >>> project.settings.get('job_runtime_limit')
+    24
 
-    >>> spider.jobs.update_tags(remove=['existing'])
+To update a project setting value by name::
+
+    >>> project.settings.set('job_runtime_limit', 20)
 
-Modifying tags is available on spider/job levels.
+Or update a few project settings at once::
+
+    >>> project.settings.update({'default_job_units': 1,
+    ...                          'job_runtime_limit': 20})
 
 
 Exceptions