Fix up the docs into reasonable shape

Make the docs include the exposed API's and be formatted
better so that they are useful to users of debtcollector instead
of not being useful.

Change-Id: I6b1bdda206927d1475cabb1872a3fe21a178b125

README.rst

@@ -1,6 +1,5 @@
-===============================
-debtcollector
-===============================
+Debtcollector
+=============
 
 A collection of python patterns that help you collect your technical debt in a
 non-destructive manner (following deprecation patterns and strategies and

doc/source/api.rst

@@ -0,0 +1,23 @@
+===
+API
+===
+
+
+The currently documented publicly exposed API's for usage in your project
+are defined below.
+
+.. warning::
+
+    External usage of internal utility functions and modules should be kept
+    to a **minimum** as they may be altered, refactored or moved to other
+    locations **without** notice (and without the typical deprecation cycle).
+
+Moves
+-----
+
+.. automodule:: debtcollector.moves
+
+Renames
+-------
+
+.. automodule:: debtcollector.renames

doc/source/conf.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import datetime
 import os
 import sys
 
@@ -22,8 +23,8 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
-    'oslosphinx'
+    'sphinx.ext.viewcode',
+    'oslosphinx',
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -38,7 +39,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'debtcollector'
-copyright = u'2013, OpenStack Foundation'
+copyright = u'%s, OpenStack Foundation' % datetime.date.today().year
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -72,4 +73,12 @@ latex_documents = [
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
+#intersphinx_mapping = {'http://docs.python.org/': None}
+
+# -- Options for autoddoc ----------------------------------------------------
+
+# Keep source order
+autodoc_member_order = 'bysource'
+
+# Always include members
+autodoc_default_flags = ['members', 'show-inheritance']

doc/source/contributing.rst

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

doc/source/index.rst

@@ -1,19 +1,23 @@
-.. debtcollector 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 debtcollector's documentation!
-========================================================
+=========================================
 
-Contents:
+.. include:: ../../README.rst
+
+.. note::
+
+    It should be noted that even though it is designed with OpenStack
+    integration in mind, and that is where most of its *current*
+    integration is it aims to be generally usable and useful in any
+    project.
+
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
-   usage
+   api
    contributing
 
 Indices and tables

doc/source/installation.rst

@@ -9,4 +9,4 @@ At the command line::
 Or, if you have virtualenvwrapper installed::
 
     $ mkvirtualenv debtcollector
-    $ pip install debtcollector
+    $ pip install debtcollector

doc/source/readme.rst

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

doc/source/usage.rst

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