Merge branch 'develop' into master

README.rst

@@ -1,41 +1,60 @@
 Uplink
 ======
+Python HTTP Made Expressive. Inspired by `Retrofit <http://square.github
+.io/retrofit/>`__.
 
-A Declarative HTTP Client for Python, inspired by `Retrofit
-<http://square.github.io/retrofit/>`__.
+|PyPI Version| |Build Status| |Coverage Status| |Documentation Status|
 
-|Build Status| |Coverage Status| |Documentation Status|
+**A Quick Walkthrough, with GitHub API v3**
 
-----
+Using decorators and function annotations, you can turn any plain old Python
+class into an HTTP API consumer:
 
-Define your API using decorators (and function annotations in Python 3):
-
-.. code:: python
+.. code-block:: python
 
     from uplink import *
 
-
+    # To register entities that are common to all API requests, you can
+    # decorate the enclosing class rather than each method separately:
     @headers({"Accept": "application/vnd.github.v3.full+json"})
     class GitHubService(object):
 
         @get("/users/{username}")
         def get_user(self, username):
             """Get a single user."""
-            pass
 
         @json
         @patch("/user")
         def update_user(self, access_token: Query, **info: Body):
             """Update an authenticated user."""
-            pass
 
-Then, **Uplink** handles the rest:
+To construct a consumer instance, use the helper function ``uplink.build``:
 
-.. code:: python
+.. code-block:: python
 
     github = build(GitHubService, base_url="https://api.github.com/")
+
+To access the GitHub API with this instance, we simply invoke any of the methods
+that we defined in the interface above. To illustrate, let's update my GitHub
+user's bio:
+
+.. code-block:: python
+
     response = github.update_user(oauth_token, bio="Beam me up, Scotty!").execute()
 
+*Voila*, ``update_user(...)`` seamlessly builds the request (using the
+decorators and annotations from the method's definition), and ``execute()``
+sends that synchronously over the network. Furthermore, the returned
+``response`` is a ``requests.Response`` (`documentation
+<http://docs.python-requests.org/en/master/api/#requests.Response>`__):
+
+.. code-block:: python
+
+    print(response.json()) # {u'disk_usage': 216141, u'private_gists': 0, ...
+
+In essence, **Uplink** delivers API consumers that are self-describing,
+reusable, and fairly compact, with minimal user effort.
+
 Installation
 ------------
 
@@ -58,3 +77,9 @@ For more details, check out the documentation at http://uplink.readthedocs.io/.
 .. |Documentation Status| image:: https://readthedocs.org/projects/uplink/badge/?version=latest
    :target: http://uplink.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
+.. |License| image:: https://img.shields.io/github/license/prkumar/uplink.svg
+   :target: https://github.com/prkumar/uplink/blob/master/LICENSE
+.. |PyPI Version| image:: https://img.shields.io/pypi/v/uplink.svg
+   :target: https://pypi.python.org/pypi/uplink
+.. |Python Version| image:: https://img.shields.io/pypi/pyversions/uplink.svg
+   :target: https://pypi.python.org/pypi/uplink

docs/source/conf.py

@@ -91,8 +91,16 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
-# html_theme_options = {}
+
+html_theme_options = {
+    "description": "A Declarative HTTP Client for Python, inspired by Retrofit.",
+    "github_user": "prkumar",
+    "github_repo": "uplink",
+    "github_button": "false",
+    "github_banner": "true",
+    "travis_button": "true",
+    "show_powered_by": "false"
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/source/index.rst

@@ -10,57 +10,97 @@ A Declarative HTTP Client for Python, inspired by `Retrofit
 
 |Release| |Python Version| |License| |Coverage Status|
 
-.. note:: **Uplink** is currently under alpha development and, thus, very
-    much under construction. Although it is not yet production ready, we
-    encourage enthusiastic early adopters to install and provide feedback,
-    as we work towards the official release. Moreover, if you're interested in
-    becoming a contributor, please feel free to reach out.
-
 ----
 
-*Beam me up, Scotty*: A GitHub API Example
-------------------------------------------
+A Quick Walkthrough, with GitHub API v3:
+----------------------------------------
 
-Define your API using decorators and function annotations with plain old
-Python methods:
+Using decorators and function annotations, you can turn any plain old Python
+class into an HTTP API consumer:
 
-.. code:: python
+.. code-block:: python
 
     from uplink import *
 
     # To register entities that are common to all API requests, you can
-    # decorate the enclosing class, instead of each method separately:
+    # decorate the enclosing class rather than each method separately:
     @headers({"Accept": "application/vnd.github.v3.full+json"})
     class GitHubService(object):
 
         @get("/users/{username}")
         def get_user(self, username):
             """Get a single user."""
-            pass
 
         @json
         @patch("/user")
         def update_user(self, access_token: Query, **info: Body):
             """Update an authenticated user."""
-            pass
 
-The helper function ``uplink.build`` turns your Python class into an
-expressive HTTP client:
+To construct a consumer instance, use the helper function :py:func:`uplink.build`:
 
-.. code:: python
+.. code-block:: python
 
     github = build(GitHubService, base_url="https://api.github.com/")
-    github.update_user(oauth_token, bio="Beam me up, Scotty!").execute()
 
+To access the GitHub API with this instance, we simply invoke any of the methods
+that we defined in the interface above. To illustrate, let's update my GitHub
+user's bio:
+
+.. code-block:: python
+
+    r = github.update_user(token, bio="Beam me up, Scotty!").execute()
+
+*Voila*, :py:meth:`update_user` seamlessly builds the request (using the
+decorators and annotations from the method's definition), and
+:py:meth:`execute` sends that synchronously over the network. Furthermore,
+the returned response :py:obj:`r` is a :py:class:`requests.Response`
+(`documentation
+<http://docs.python-requests.org/en/master/api/#requests.Response>`__):
+
+.. code-block:: python
+
+    print(r.json()) # {u'disk_usage': 216141, u'private_gists': 0, ...
+
+In essence, **Uplink** delivers API consumers that are self-describing,
+reusable, and fairly compact, with minimal user effort.
+
+----
+
+.. note::
+
+   **Uplink** is currently in initial development and, therefore, not
+   production ready at the moment. Furthermore, as the package follows the
+   `Semantic Versioning Specification <http://semver.org/>`__, the public
+   API outlined in this documentation should not be considered stable until the
+   release of :code:`v1.0.0`.
+
+   However, while **Uplink** is under construction, we invite eager users
+   to install early and provide open feedback, which can be as simple as
+   opening a GitHub issue when you notice a missing feature, latent defect,
+   documentation oversight, etc.
+
+   Moreover, for those interested in contributing, I plan to publish a
+   contribution guide soon, but in the meantime, please feel free to fork
+   the `repository on GitHub <https://github.com/prkumar/uplink>`__ and open
+   a pull request ('tis
+   `Hacktoberfest <https://hacktoberfest.digitalocean.com/>`__, after all)!
+
+The User Manual
+---------------
+
+This guide describes the package's Public API.
 
 .. toctree::
    :maxdepth: 2
 
+   install.rst
+   types.rst
+
 .. |Coverage Status| image:: https://coveralls.io/repos/github/prkumar/uplink/badge.svg?branch=master
    :target: https://coveralls.io/github/prkumar/uplink?branch=master
-.. |Release| image:: https://img.shields.io/github/release/prkumar/uplink.svg
-   :target: https://pypi.python.org/pypi/uplink
+.. |License| image:: https://img.shields.io/github/license/prkumar/uplink.svg
+   :target: https://github.com/prkumar/uplink/blob/master/LICENSE
 .. |Python Version| image:: https://img.shields.io/pypi/pyversions/uplink.svg
    :target: https://pypi.python.org/pypi/uplink
-.. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg
-   :target: https://opensource.org/licenses/MIT)
+.. |Release| image:: https://img.shields.io/github/release/prkumar/uplink/all.svg
+   :target: https://github.com/prkumar/uplink

docs/source/install.rst

@@ -0,0 +1,35 @@
+Installation
+============
+
+Getting started with Uplink begins with installation.
+
+Using ``pip``
+-------------
+
+With ``pip`` or ``pipenv`` installed, you can install Uplink simply by
+typing:
+
+::
+
+    $ pip install uplink
+
+
+Download the Source Code
+------------------------
+
+Uplink's source code is in a `public repository hosted on GitHub
+<https://github.com/prkumar/uplink>`__.
+
+As an alternative to installing with ``pip``, you could clone the repository
+
+::
+
+    $ git clone https://github.com/prkumar/uplink.git
+
+Then, install; e.g., with ``setup.py``:
+
+::
+
+    $ cd uplink
+    $ python setup.py install
+