Docs cleanup

Massage the default cookiecutter-provided structire to remove Sphinx
errors and make it our own.

Change-Id: I2996b793f6ef5881749a9fc3b7ce7d202a6a1349

README.rst

@@ -1,5 +1,38 @@
-===================
-python-openstacksdk
-===================
+====================
+OpenStack Python SDK
+====================
+
+``python-openstacksdk`` is a ground-up implementation of a Python
+API and SDK for OpenStack REST services.
+
+
+Building Documentation
+----------------------
+
+This documentation is written by contributors, for contributors.
+
+The source is maintained in the ``doc/source`` folder using
+`reStructuredText`_ and built by `Sphinx`_
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Sphinx: http://sphinx.pocoo.org/
+
+* Building Manually::
+
+    $ python setup.py build_sphinx
+
+Results are in the `build/sphinx/html` directory.
+
+Requirements
+------------
+
+* Python 2.6+, Python 3.3+
+* httpretty
+* pbr
+* requests
+
+License
+-------
+
+Apache 2.0
 
-* Free software: Apache license

doc/source/contributing.rst

@@ -1 +1,14 @@
+Contributing
+============
+
+python-openstacksdk is a Stackforge project, mirrored on `GitHub`_.  Bugs and
+Blueprints are handled on `Launchpad`_.  Code reviews are hosted on `Gerrit`_.
+
+.. _GitHub: https://github.com/stackforge/python-openstacksdk
+.. _Launchpad: https://launchpad.net/unifiedsdk
+.. _Gerrit: https://review.openstack.org/#/q/project:stackforge/python-openstacksdk,n,z
+
+OpenStack Contributions
+-----------------------
+
 .. include:: ../../CONTRIBUTING.rst

doc/source/index.rst

@@ -1,12 +1,13 @@
-Welcome to python-openstacksdk's documentation!
-===============================================
+python-openstacksdk
+===================
 
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   readme
    installation
    usage
    contributing
+
+.. include:: ../../README.rst

doc/source/installation.rst

@@ -2,6 +2,17 @@
 Installation
 ============
 
+During Development
+------------------
+
+Get the source::
+
+    $ git clone https://github.com/stackforge/python-openstacksdk
+    $ python setup.py install
+
+After the Initial Release
+-------------------------
+
 At the command line::
 
     $ pip install python-openstacksdk

doc/source/readme.rst

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