[DOCS] Use new documentation tree structure

Change to the new structure we are adopting for each role, plus some
general cleanup.

Change-Id: Ife0365ef1a23227108afba2770e7887e2fc0227e

CONTRIBUTING.rst

@@ -1,11 +1,9 @@
-repo_build
+===================================================
-########
+OpenStack-Ansible repo_build contributor guidelines
+===================================================
 
-contributor guidelines
+Filing bugs
-^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~
-
-Filing Bugs
------------
 
 Bugs should be filed on Launchpad, not GitHub: "https://bugs.launchpad.net/openstack-ansible"
 
@@ -18,8 +16,8 @@ When submitting a bug, or working on a bug, please ensure the following criteria
     * Steps to reproduce the problem if possible.
 
 
-Submitting Code
+Submitting code
----------------
+~~~~~~~~~~~~~~~
 
 Changes to the project should be submitted for review via the Gerrit tool, following
 the workflow documented at: "http://docs.openstack.org/infra/manual/developers.html#development-workflow"
@@ -28,7 +26,7 @@ Pull requests submitted through GitHub will be ignored and closed without regard
 
 
 Extra
------
+~~~~~
 
 Tags:
     If it's a bug that needs fixing in a branch in addition to Master, add a '\<release\>-backport-potential' tag (eg ``juno-backport-potential``).  There are predefined tags that will autocomplete.
@@ -41,7 +39,7 @@ Importance:
 
 
 Style guide
------------
+~~~~~~~~~~~
 
 When creating tasks and other roles for use in Ansible please create them using the YAML dictionary format.
 
@@ -71,7 +69,7 @@ Usage of the ">" and "|" operators should be limited to Ansible conditionals and
 
 
 Issues
-------
+~~~~~~
 
 When submitting an issue, or working on an issue please ensure the following criteria are met:
     * The description clearly states or describes the original problem or root cause of the problem.

README.rst

@@ -1,13 +1,12 @@
-====================
+============================
-OpenStack repo build
+OpenStack-Ansible repo_build
-====================
+============================
 
-Role to deploy a repository build for both python packages and git sources.
+Ansible role that builds a repository of Git repositories, Python
+wheels, and virtualenvs.
 
-.. code:: yaml
+Documentation for the project can be found at:
+  http://docs.openstack.org/developer/openstack-ansible-repo_build
 
-   - name: Setup repo builds
+The project home is at:
-      hosts: repo_all
+  http://launchpad.net/openstack-ansible
-      user: root
-      roles:
-        - { role: "repo_build", tags: [ "repo-build" ] }

doc/source/index.rst

@@ -1,10 +1,24 @@
-``repo_build`` docs
+============================
-===================
+OpenStack-Ansible repo_build
+============================
 
-Ansible role for building a python repository of wheels and venvs.
+Ansible role that builds a repository of Git repositories, Python
+wheels, and virtualenvs.
 
-Basic role example
+Default variables
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../defaults/main.yml
+   :language: yaml
+   :start-after: under the License.
+
+Required variables
 ~~~~~~~~~~~~~~~~~~
 
+None.
+
+Example playbook
+~~~~~~~~~~~~~~~~
+
 .. literalinclude:: ../../examples/playbook.yml
    :language: yaml

example/playbook.yml

@@ -1,2 +0,0 @@
-    - role: "repo_build"
-      ROLE_VARS...

examples/playbook.yml

@@ -0,0 +1,5 @@
+- name: Set up repo builds
+  hosts: repo_all
+  user: root
+  roles:
+    - { role: "repo_build", tags: [ "repo-build" ] }

releasenotes/source/index.rst

@@ -1,6 +1,6 @@
-================================
+==========================================
- OpenStack-Ansible Release Notes
+OpenStack-Ansible repo_build release notes
-================================
+==========================================
 
 .. toctree::
    :maxdepth: 1

releasenotes/source/mitaka.rst

@@ -1,6 +1,6 @@
-=============================
+===========================
- Mitaka Series Release Notes
+Mitaka series release notes
-=============================
+===========================
 
 .. release-notes::
    :branch: origin/stable/mitaka

releasenotes/source/unreleased.rst

@@ -1,5 +1,5 @@
-==============================
+============================
- Current Series Release Notes
+Current series release notes
-==============================
+============================
 
 .. release-notes::

setup.cfg

@@ -5,7 +5,7 @@ description-file =
     README.rst
 author = OpenStack
 author-email = openstack-dev@lists.openstack.org
-home-page = http://www.openstack.org/
+home-page = http://docs.openstack.org/developer/openstack-ansible-repo_build
 classifier =
     Intended Audience :: Developers
     Intended Audience :: System Administrators