Minor improvements for the docs

Author: vshlapakov

docs/client/overview.rst

@@ -44,7 +44,7 @@ And select a particular project to work with::
     >>> project.key
     '123'
 
-The above is a shortcut for ``client.projects.get(123)``.
+.. tip:: The above is a shortcut for ``client.projects.get(123)``.
 
 Project
 -------
@@ -60,13 +60,15 @@ For example, to schedule a spider run (it returns a job object)::
 
 Project instance also has the following fields:
 
-- activity - access to project activity records
-- collections - work with project collections (see ``Collections`` section)
-- frontiers - using project frontier (see ``Frontiers`` section)
-- settings - interface to project settings
-- spiders - access to spiders collection (see ``Spiders`` section)
+- **activity** - access to :ref:`project activity <project-activity>` records
+- **collections** - work with :ref:`project collections <project-collections>`
+- **frontiers** - using :ref:`project frontiers <project-frontiers>`
+- **settings** - interface to :ref:`project settings <project-settings>`
+- **spiders** - access to :ref:`spiders collection <project-spiders>`
 
 
+.. _project-settings:
+
 Settings
 --------
 
@@ -89,6 +91,7 @@ Or update a few project settings at once::
     >>> project.settings.update({'default_job_units': 1,
     ...                          'job_runtime_limit': 20})
 
+.. _project-spiders:
 
 Spiders
 -------
@@ -111,6 +114,8 @@ To select a particular spider to work with::
     >>> spider.name
     spider2
 
+.. _spider:
+
 Spider
 ------
 
@@ -123,6 +128,8 @@ To schedule a spider run::
 
 Note that you don't need to specify spider name explicitly.
 
+.. _jobs:
+
 Jobs
 ----
 
@@ -299,6 +306,8 @@ To delete a job::
 
     >>> job.delete()
 
+.. _job-metadata:
+
 Metadata
 ^^^^^^^^
 
@@ -324,6 +333,8 @@ Anything can be stored in metadata, here is example how to add tags::
 
     >>> job.metadata.set('tags', ['obsolete'])
 
+.. _job-items:
+
 Items
 ^^^^^
 
@@ -332,6 +343,8 @@ To retrieve all scraped items from a job::
     >>> for item in job.items.iter():
     ...     # do something with item (it's just a dict)
 
+.. _job-logs:
+
 Logs
 ^^^^
 
@@ -346,6 +359,8 @@ To retrieve all log entries from a job::
       'time': 1482233733976},
     }
 
+.. _job-requests:
+
 Requests
 ^^^^^^^^
 
@@ -364,6 +379,8 @@ To retrieve all requests from a job::
       'url': 'https://example.com'
     }]
 
+.. _job-samples:
+
 Samples
 ^^^^^^^
 
@@ -374,6 +391,7 @@ To retrieve all samples for a job::
     >>> sample
     [1482233732452, 0, 0, 0, 0, 0]
 
+.. _project-activity:
 
 Activity
 --------
@@ -401,6 +419,8 @@ Or post multiple events at once::
     >>> project.activity.add(events)
 
 
+.. _project-collections:
+
 Collections
 -----------
 
@@ -427,6 +447,8 @@ Usual workflow with `Collections`_ would be::
 
 Collections are available on project level only.
 
+.. _project-frontiers:
+
 Frontiers
 ---------
 
@@ -526,6 +548,8 @@ Close batch writers of all frontiers of a project::
 
 Frontiers are available on project level only.
 
+.. _job-tags:
+
 Tags
 ----
 
@@ -552,7 +576,7 @@ Exceptions
 scrapinghub.exceptions.ScrapinghubAPIError
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Base exception class.
+Base exception class for all other exceptions listed below.
 
 
 scrapinghub.exceptions.BadRequest

docs/legacy/connection.rst

@@ -1,7 +1,9 @@
-scrapinghub.legacy.Connection
-=============================
+scrapinghub.Connection
+======================
 
-TODO add short description & deprecation message here!
+The module is the very first Python library for communicating with the Scrapinghub API.
+
+[WARNING] It is deprecated, please use `scrapinghub.ScrapinghubClient`_ instead.
 
 Overview
 --------
@@ -106,3 +108,6 @@ Module contents
     :members:
     :undoc-members:
     :show-inheritance:
+
+
+.. _scrapinghub.ScrapinghubClient: ../client/overview.html

docs/legacy/hubstorage.rst

@@ -1,10 +1,9 @@
-scrapinghub.hubstorage.HubstorageClient
-=======================================
+scrapinghub.HubstorageClient
+============================
 
-TODO add short description & deprecation message here!
+The library can be used for interaction with spiders, jobs and scraped data through ``storage.scrapinghub.com`` endpoints.
 
-
-The library can also be used for interaction with spiders, jobs and scraped data through ``storage.scrapinghub.com`` endpoints.
+[WARNING] It is deprecated, please use `scrapinghub.ScrapinghubClient`_ instead.
 
 
 Overview
@@ -246,3 +245,5 @@ Module contents
     :members:
     :undoc-members:
     :show-inheritance:
+
+.. _scrapinghub.ScrapinghubClient: ../client/overview.html 

docs/quickstart.rst

@@ -14,7 +14,7 @@ The quick way::
 
     pip install scrapinghub
 
-You can also install the library with MessagePack support, it provides better
+You can also install the library with `MessagePack`_ support, it provides better
 response time and improved bandwidth usage::
 
     pip install scrapinghub[msgpack]
@@ -50,13 +50,13 @@ Access your jobs data::
         'size': 35000,
     }
 
-Many more feature are awaiting for you.
+Many more features `are awaiting`_ for you.
 
 
 Tests
 -----
 
-The package is covered with integration tests based on `VCR.py library`_: there
+The package is covered with integration tests based on `VCR.py`_ library: there
 are recorded cassettes files in ``tests/*/cassettes`` used instead of HTTP
 requests to real services, it helps to simplify and speed up development.
 
@@ -80,4 +80,6 @@ If you want to update/recreate all the cassettes from scratch, please use::
 Note that internally the above command erases the whole folder with cassettes.
 
 
-.. _VCR.py library: https://pypi.python.org/pypi/vcrpy
+.. _MessagePack: https://en.wikipedia.org/wiki/MessagePack
+.. _are awaiting: client/overview.html
+.. _VCR.py: https://pypi.python.org/pypi/vcrpy