updated documentation

README.md

@@ -1,11 +1,15 @@
 [![PyPI version](https://badge.fury.io/py/hoverpy.svg)](https://testpypi.python.org/pypi/hoverpy) [![RTD badget](https://readthedocs.org/projects/pip/badge/?version=latest)](http://hoverpy.readthedocs.io/en/latest/)[![Build Status](https://travis-ci.org/SpectoLabs/hoverpy.svg?branch=master)](https://travis-ci.org/SpectoLabs/hoverpy)
 
-![logo](https://github.com/SpectoLabs/hoverpy/raw/master/docs/source/hoverpy_logo.png)
+![](https://github.com/SpectoLabs/hoverpy/raw/master/docs/source/hoverpy_logo.png)
 
 ### Documentation
 
 https://hoverpy.readthedocs.io/
 
+### Source
+
+https://github.com/SpectoLabs/hoverpy/
+
 ### Motivation
 
 HoverPy speeds up and simplifies tests that depend on HTTP / HTTPS services. It does so by recording all HTTP traffic generated by your python application inside a database file. 

docs/source/README.rst

@@ -0,0 +1,57 @@
+|PyPI version| |RTD badget|\ |Build Status|
+
+.. figure:: https://github.com/SpectoLabs/hoverpy/raw/master/docs/source/hoverpy_logo.png
+   :alt: 
+
+Documentation
+~~~~~~~~~~~~~
+
+https://hoverpy.readthedocs.io/
+
+Source
+~~~~~~
+
+https://github.com/SpectoLabs/hoverpy/
+
+Motivation
+~~~~~~~~~~
+
+HoverPy speeds up and simplifies tests that depend on HTTP / HTTPS
+services. It does so by recording all HTTP traffic generated by your
+python application inside a database file.
+
+When you run your code again, it plays back the responses corresponding
+to your requests. This means during the simulate phase, no HTTP traffic
+gets generated whatsoever. This grants several benefits:
+
+-  Increased test speed
+-  Ability to work offline
+-  Ability to modify traffic
+-  Ability to simulate network latency
+-  Deterministic test environment
+
+If/when the service you are testing against changes its API, then you
+can simply delete your db file, and capture the test results again.
+HoverPy uses a `very high performance proxy written in
+Go <http://hoverfly.io>`__, for this reason it is rock solid in terms of
+speed and reliability.
+
+Support
+~~~~~~~
+
+HoverPy works great with the following HTTP clients:
+
+-  requests
+-  TBD
+
+License
+~~~~~~~
+
+HoverPy uses Apache License V2. See LICENSE.txt for more details.
+
+.. |PyPI version| image:: https://badge.fury.io/py/hoverpy.svg
+   :target: https://testpypi.python.org/pypi/hoverpy
+.. |RTD badget| image:: https://readthedocs.org/projects/pip/badge/?version=latest
+   :target: http://hoverpy.readthedocs.io/en/latest/
+.. |Build Status| image:: https://travis-ci.org/SpectoLabs/hoverpy.svg?branch=master
+   :target: https://travis-ci.org/SpectoLabs/hoverpy

docs/source/basic.rst

@@ -1,6 +1,6 @@
 .. basic
 
-Basic Example
+Basic
 ********
 
 

docs/source/conf.py

@@ -17,6 +17,14 @@
 import shlex
 import sys
 
+from recommonmark.parser import CommonMarkParser
+
+source_parsers = {
+    '.md': CommonMarkParser,
+}
+
+source_suffix = ['.rst', '.md']
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -41,7 +49,7 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+# source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -131,7 +139,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = "fly.png"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

docs/source/delays.rst

@@ -1,6 +1,6 @@
 .. delays
 
-delays Example
+delays
 ********
 
 

docs/source/examples.rst

@@ -0,0 +1,65 @@
+Examples
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   basic.rst
+   readthedocs.rst
+   modify.rst
+   delays.rst
+   unittesting.rst
+
+basic
+-----
+
+.. code:: bash
+
+    python examples/basic/basic.py
+
+This is the most basic example possible. Captures one request, and
+replays it.
+
+`readthedocs <readthedocs.html>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+    python examples/readthedocs/readthedocs.py
+
+Slightly more advanced example, where we query readthedocs.io for
+articles, get these articles. The program can be run in capture or
+simulate mode, and the functionality is timed.
+
+`delays <delays.html>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+    python examples/delays/delays.py
+
+Demonstrates how to add latency to calls, based on host, and method
+type.
+
+`modify <modify.html>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+    python examples/modify/modify.py
+
+Demonstrations how to modify requests. This is particularly useful for
+sending curved balls to your applications, and make sure they deal with
+them correctly.
+
+`unittesting <unittesting.html>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+    env HOVERPY_CAPTURE=true python examples/unittesting/unittesting.py
+    python examples/unittesting/unittesting.py
+
+Demonstrates how to use the ``hoverpy.TestCase`` class for unit testing
+purposes.
+

docs/source/index.rst

@@ -1,124 +1,21 @@
-HoverPy
-=======
+HoverPy |version| Documentation
+*********************
 
-|PyPI version| |RTD badget|\ |Build Status|
+.. include:: README.rst
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
-
-Hoverpy is a Python library that enables you to transparently use
-`HoverFly <https://github.com/SpectoLabs/hoverfly>`__ in your python
-applications.
-
-Hoverfly is a lightweight, open source service virtualization tool.
-Using Hoverfly, you can virtualize your application dependencies to
-create a self-contained development or test environment.
-
-Installation
-------------
-
-If you plan on trying out the examples:
-
-.. code:: bash
-
-    git clone https://github.com/SpectoLabs/hoverpy.git
-    cd hoverpy
-    python setup.py test
-
-    # please note, this is not required for running the examples, only for installing your local copy:
-    # sudo python setup.py install
-
-Or whether you just want to install it using pip (not yet recommended):
-
-.. code:: bash
-
-    pip install --user -i https://testpypi.python.org/pypi hoverpy
-
-Test
-----
-
-.. code:: bash
-
-    make test
-    # or
-    python setup.py test
-
-Examples
---------
+Contents
+========
 
 .. toctree::
-   :maxdepth: 1
-
-   basic.rst
-   readthedocs.rst
-   modify.rst
-   delays.rst
-   unittesting.rst
-
-`basic <basic.html>`__
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: bash
+   :maxdepth: 2
 
-    python examples/basic/basic.py
+   installation.rst
+   usage.rst
 
-This is the most basic example possible. Captures one request, and
-replays it.
+==================
+Indices and tables
+==================
 
-`readthedocs <readthedocs.html>`__
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: bash
-
-    python examples/readthedocs/readthedocs.py
-
-Slightly more advanced example, where we query readthedocs.io for
-articles, get these articles. The program can be run in capture or
-simulate mode, and the functionality is timed.
-
-`delays <delays.html>`__
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: bash
-
-    python examples/delays/delays.py
-
-Demonstrates how to add latency to calls, based on host, and method
-type.
-
-`modify <modify.html>`__
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: bash
-
-    python examples/modify/modify.py
-
-Demonstrations how to modify requests. This is particularly useful for
-sending curved balls to your applications, and make sure they deal with
-them correctly.
-
-`unittesting <unittesting.html>`__
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: bash
-
-    env HOVERPY_CAPTURE=true python examples/unittesting/unittesting.py
-    python examples/unittesting/unittesting.py
-
-Demonstrates how to use the ``hoverpy.TestCase`` class for unit testing
-purposes.
-
---------------
-
-|logo|
-======
-
-.. |PyPI version| image:: https://badge.fury.io/py/hoverpy.svg
-   :target: https://testpypi.python.org/pypi/hoverpy
-.. |RTD badget| image:: https://readthedocs.org/projects/pip/badge/?version=latest
-   :target: http://hoverpy.readthedocs.io/en/latest/
-.. |Build Status| image:: https://travis-ci.org/SpectoLabs/hoverpy.svg?branch=master
-   :target: https://travis-ci.org/SpectoLabs/hoverpy
-.. |logo| image:: https://github.com/SpectoLabs/hoverfly/raw/master/core/static/img/hoverfly_logo.png
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/installation.rst

@@ -0,0 +1,30 @@
+.. installation
+
+Installation
+------------
+
+If you plan on trying out the examples:
+
+.. code:: bash
+
+    git clone https://github.com/SpectoLabs/hoverpy.git
+    cd hoverpy
+    python setup.py test
+
+    # please note, this is not required for running the examples, only for installing your local copy:
+    # sudo python setup.py install
+
+Or whether you just want to install it using pip (not yet recommended):
+
+.. code:: bash
+
+    pip install --user -i https://testpypi.python.org/pypi hoverpy
+
+Test
+----
+
+.. code:: bash
+
+    make test
+    # or
+    python setup.py test

docs/source/modify.rst

@@ -1,6 +1,6 @@
 .. modify
 
-modify Example
+modify
 ********
 
 

docs/source/readthedocs.rst

@@ -1,6 +1,6 @@
 .. readthedocs
 
-readthedocs Example
+readthedocs
 ********
 
 
@@ -38,7 +38,8 @@ This function requests articles from readthedocs.io.
         print("\nGetting links in %s mode!\n" % hp.mode())
         start = time.time()
         sites = requests.get(
-            "http://readthedocs.org/api/v1/project/?limit=%d&offset=0&format=json" % limit)
+            "http://readthedocs.org/api/v1/project/?limit="
+            "%d&offset=0&format=json" % int(limit))
         objects = sites.json()['objects']
         links = ["http://readthedocs.org" + x['resource_uri'] for x in objects]
         for link in links:

docs/source/unittesting.rst

@@ -1,6 +1,6 @@
 .. unittesting
 
-unittesting Example
+unittesting
 ********