usage docs, rst link formatting

README.rst

@@ -6,15 +6,46 @@ Python 3 Aptly API client
 
 
 This is a thin abstraction layer for interfacing with
-[Aptly's HTTP API](https://www.aptly.info/doc/api/). It's used by
-[GoPythonGo](https://github.com/gopythongo/gopythongo/), but can be used as a
-standalone library from Pypi.
+`Aptly's HTTP API <https://www.aptly.info/doc/api/>`__. It's used by
+`GoPythonGo <https://github.com/gopythongo/gopythongo/>`__, but can be used as
+a standalone library from Pypi.
 
-.. code-block:: python
+.. code-block:: shell
 
     pip install aptly-api-client
 
 
+Usage
+-----
+
+The library provides a direct abstraction of the published Aptly API, mostly
+using the same naming, only replacing it with pythonic naming where necessary.
+All code has full `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`__
+annotations, so if you're using a modern IDE, using this library should be
+especially straight-forward.
+
+Where appropriate, the library exposes the interface of the underlying
+``requests`` library. This allows you to configure CA pinning, SSL client
+certificates, HTTP Basic authentication etc.
+
+.. code-block:: python
+
+# initialize a client
+from aptly_api import Client
+aptly = Client("http://aptly-endpoint.test/")
+
+# create a repository
+aptly.repos.create("myrepo", comment="a test repo",
+                   default_distribution="mydist",
+                   default_component="main")
+
+# upload a package
+aptly.files.upload("test_folder", "/tmp/mypkg_1.0_amd64.deb")
+
+# add the package to the repo
+aptly.repos.add_uploaded_file("myrepo", "test_folder")
+
+
 License
 =======