Vastly improve the docs

Change-Id: I0a840818520463652e9cfc2c159145b825747e7a

README.rst

@@ -8,20 +8,3 @@ Code from the future, delivered to you in the **now**.
 * Documentation: http://docs.openstack.org/developer/futurist
 * Source: http://git.openstack.org/cgit/openstack/futurist
 * Bugs: http://bugs.launchpad.net/futurist
-
-Features
---------
-
-* A ``futurist.GreenThreadPoolExecutor`` using `eventlet`_ green thread
-  pools. It provides a standard `executor`_ API/interface and it also gathers
-  execution statistics.
-* A ``futurist.ProcessPoolExecutor`` derivative that gathers execution
-  statistics.
-* A ``futurist.SynchronousExecutor`` that **doesn't** run concurrently. It
-  has the same `executor`_ API/interface and it also gathers execution
-  statistics.
-* A ``futurist.ThreadPoolExecutor`` derivative that gathers execution
-  statistics.
-
-.. _eventlet: http://eventlet.net/
-.. _executor: https://docs.python.org/dev/library/concurrent.futures.html#executor-objects

doc/source/api.rst

@@ -0,0 +1,36 @@
+===
+API
+===
+
+---------
+Executors
+---------
+
+.. autoclass:: futurist.GreenThreadPoolExecutor
+    :members:
+
+.. autoclass:: futurist.ProcessPoolExecutor
+    :members:
+
+.. autoclass:: futurist.SynchronousExecutor
+    :members:
+
+.. autoclass:: futurist.ThreadPoolExecutor
+    :members:
+
+-------
+Futures
+-------
+
+.. autoclass:: futurist.Future
+    :members:
+
+.. autoclass:: futurist.GreenFuture
+    :members:
+
+-------------
+Miscellaneous
+-------------
+
+.. autoclass:: futurist.ExecutorStatistics
+    :members:

doc/source/contributing.rst

@@ -1,4 +1,5 @@
 ============
 Contributing
 ============
+
 .. include:: ../../CONTRIBUTING.rst

doc/source/features.rst

@@ -0,0 +1,20 @@
+========
+Features
+========
+
+* A :py:class:`.futurist.GreenThreadPoolExecutor` using `eventlet`_ green thread
+  pools. It provides a standard `executor`_ API/interface and it also gathers
+  execution statistics. It returns instances of
+  :py:class:`.futurist.GreenFuture` objects.
+* A :py:class:`.futurist.ProcessPoolExecutor` derivative that gathers execution
+  statistics. It returns instances of :py:class:`.futurist.Future` objects.
+* A :py:class:`.futurist.SynchronousExecutor` that **doesn't** run
+  concurrently. It has the same `executor`_ API/interface and it also
+  gathers execution statistics. It returns instances
+  of :py:class:`.futurist.Future` objects.
+* A :py:class:`.futurist.ThreadPoolExecutor` derivative that gathers
+  execution statistics. It returns instances
+  of :py:class:`.futurist.Future` objects.
+
+.. _eventlet: http://eventlet.net/
+.. _executor: https://docs.python.org/dev/library/concurrent.futures.html#executor-objects

doc/source/index.rst

@@ -1,19 +1,14 @@
-.. futurist documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to futurist's documentation!
 ========================================================
 
-Contents:
+Code from the future, delivered to you in the **now**.
 
 .. toctree::
    :maxdepth: 2
 
-   readme
+   features
+   api
    installation
-   usage
    contributing
 
 Indices and tables

doc/source/readme.rst

@@ -1 +0,0 @@
-.. include:: ../../README.rst

doc/source/usage.rst

@@ -1,7 +0,0 @@
-========
-Usage
-========
-
-To use futurist in a project::
-
-    import futurist

futurist/_futures.py

@@ -273,6 +273,8 @@ class _GreenWorker(object):
 
 
 class GreenFuture(Future):
+    __doc__ = Future.__doc__
+
     def __init__(self):
         super(GreenFuture, self).__init__()
         if not _utils.EVENTLET_AVAILABLE: