Adding documentation for the Python API (#99)

* Adding documentation for the Python API

* Sphinx work

Added set query usage and tweaked sphinx auto-doc for the better

* Review feedback for SEO and BULK

* Review feedback and finishing up API model section

* Adding build, documentation, and pypi badges

* Making title sound less generic

* Changing core project link

docs/api.rst

@@ -1,18 +1,59 @@
 API
 ===
 
-.. module:: pynsot.client
+.. module:: pynsot
 
 This part of the documentation is for API reference
 
 Clients
 -------
 
+.. automodule:: pynsot.client
+
 .. autofunction:: get_api_client
 .. autoclass:: BaseClient
+   :members:
+
 .. autoclass:: EmailHeaderClient
+   :members:
+
 .. autoclass:: AuthTokenClient
+   :members:
+
 .. autoclass:: BaseClientAuth
+   :members:
+
 .. autoclass:: EmailHeaderAuthentication
+   :members:
+
 .. autoclass:: AuthTokenAuthentication
+   :members:
+
+
+API Models
+----------
+
+.. automodule:: pynsot.models
+
+.. autoclass:: Resource
+   :members:
+
+.. autoclass:: Network
+   :members:
+
+.. autoclass:: Device
+   :members:
+
+.. autoclass:: Interface
+   :members:
+
+Utilities
+---------
+
+.. autofunction:: pynsot.util.get_result
+.. autofunction:: pynsot.util.get_result_key
+
+Dotfile
+-------
 
+.. autoclass:: pynsot.dotfile.Dotfile

docs/auth.rst

@@ -13,31 +13,34 @@ The client default is ``auth_token``, but ``auth_header`` is more flexible for
 If sticking with the defaults, you'll need to retrieve your key from
 ``/profile`` in the web interface.
 
-Client
-------
+Refer to :ref:`config_ref` for setting these in your ``pynsotrc``
 
-.. note::
-    The preferred method is to configure your pynsotrc as you wish and then use
-    ``pynsot.client.get_api_client`` for easier code re-use. Should you need
-    something more manual, proceed
+Python Client
+-------------
 
-Following will show you how to set up a client object in Python:
+Assuming your configuration is correct, the CLI interface doesn't need anything
+special to make authentication work. The following only applies to retrieving a
+client instance in Python.
 
 .. code-block:: python
 
    from pynsot.client import AuthTokenClient, EmailHeaderClient, get_api_client
 
-   # PREFERRED
+   # This is the preferred method, returning the appropriate client according
+   # to your dotfile if no arguments are supplied.
+   #
+   # Alteratively you can override options by passing url, auth_method, and
+   # other kwargs. See `help(get_api_client) for more details
    c = get_api_client()
 
-   # OR
+   # OR using the client objects directly
 
    email = 'jathan@localhost'
    secret_key = 'qONJrNpTX0_9v7H_LN1JlA0u4gdTs4rRMQklmQF9WF4='
    url = 'http://localhost:8990/api'
-   c = Client(url, email=email, secret_key=secret_key)
+   c = AuthTokenClient(url, email=email, secret_key=secret_key)
 
-   # OR
+   # Email Header Client
    domain = 'localhost'
    auth_header = 'X-NSoT-Email'
    c = EmailHeaderClient(

docs/cli.rst

@@ -124,6 +124,8 @@ Each resource's ``list`` action supports ``-i/--id``, ``-l/--limit`` and
 * The ``-l/--limit`` option will limit the set of results to ``N`` resources.
 * The ``-o/--offset`` option will skip the first ``N`` resources.
 
+.. _set_queries:
+
 Set Queries
 ~~~~~~~~~~~
 

docs/index.rst

@@ -1,12 +1,23 @@
-Welcome to pynsot's documentation!
-==================================
-
+Pynsot - The Network Source of Truth Client
+===========================================
 
 Pynsot is the official client library and command-line utility for the
-:abbr:`NSoT (Network Source of Truth)` IPAM.  For more information on the core
-project, please check it out `here`_.
-
-.. _here: https://github.com/dropbox/nsot
+`Network Source of Truth (NSoT)`_ IPAM.  For more information on the core
+project, please follow the link above.
+
+|Build Status| |Documentation Status| |PyPI Status|
+
+.. _Network Source of Truth (NSoT): https://github.com/dropbox/nsot
+
+.. |Build Status| image:: https://img.shields.io/travis/dropbox/pynsot/master.svg?style=flat
+   :target: https://travis-ci.org/dropbox/pynsot
+   :width: 88px
+.. |Documentation Status| image:: https://readthedocs.org/projects/pynsot/badge/?version=latest&style=flat
+   :target: https://readthedocs.org/projects/pynsot/?badge=latest
+   :width: 76px
+.. |PyPI Status| image:: https://img.shields.io/pypi/v/pynsot.svg?style=flat
+   :target: https://pypi.python.org/pypi/pynsot
+   :width: 86px
 
 .. warning::
     This project is still very much in flux and likely to have