rearrange existing documentation to fit the new standard layout

Some minor formatting issues caused by openstackdocstheme adoption
in README.rst and HACKING.rst.

Note that the install instruction is part of README, so it is not split
out into a separate rst file (as suggested in the doc-migration spec).

Change-Id: Iac58eeb15921e9225a461e3b5b2f3bd7ac99f415

HACKING.rst

@@ -315,7 +315,7 @@ OpenStack Trademark
 -------------------
 
 OpenStack is a registered trademark of the OpenStack Foundation, and uses the
-following capitalization:
+following capitalization::
 
    OpenStack
 
@@ -349,5 +349,4 @@ readable.
 For further information on constructing high quality commit messages,
 and how to split up commits into a series of changes, consult the
 project wiki:
-
-   https://wiki.openstack.org/GitCommitMessages
+https://wiki.openstack.org/GitCommitMessages

README.rst

@@ -10,9 +10,9 @@ introduce new rules, or make existing rules stricter.
 Installation
 ============
 
-hacking is available from pypi, so just run:
+hacking is available from pypi, so just run::
 
-  ``pip install hacking``
+  pip install hacking
 
 This will install specific versions of ``flake8`` with the ``hacking``,
 ``pep8``, ``mccabe`` and ``pyflakes`` plugins.

doc/source/index.rst

@@ -1,9 +1,14 @@
-.. include:: ../../HACKING.rst
+================================================
+hacking: OpenStack Hacking Guideline Enforcement
+================================================
 
-Readme
-======
+hacking is a set of flake8 plugins that test and enforce the :ref:`StyleGuide`.
+
+Hacking pins its dependencies, as a new release of some dependency can break
+hacking based gating jobs. This is because new versions of dependencies can
+introduce new rules, or make existing rules stricter.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
 
-   readme
+   user/index

doc/source/readme.rst

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

doc/source/user/hacking.rst

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

doc/source/user/index.rst

@@ -0,0 +1,9 @@
+==================
+User Documentation
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   hacking
+   usage

doc/source/user/usage.rst

@@ -0,0 +1,5 @@
+=============
+Using hacking
+=============
+
+.. include:: ../../../README.rst