rearrange content to fit the new standard layout

Part of doc-migration work

The proposed document strucutre is documented at:
http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html

Change-Id: Idea4f21bb66fbdf4b4f8925f2260f43374a108f3

CONTRIBUTING.rst

@@ -1,17 +1,14 @@
 If you would like to contribute to the development of OpenStack, you must
 follow the steps in this page:
-
 http://docs.openstack.org/infra/manual/developers.html
 
 If you already have a good understanding of how the system works and your
 OpenStack accounts are set up, you can skip to the development workflow
 section of this documentation to learn how changes to OpenStack should be
 submitted for review via the Gerrit tool:
-
 http://docs.openstack.org/infra/manual/developers.html#development-workflow
 
 Pull requests submitted through GitHub will be ignored.
 
 Bugs should be filed on Launchpad, not GitHub:
-
 https://bugs.launchpad.net/neutron-lib

doc/source/contributor/contributing.rst

@@ -1,7 +1,8 @@
 ============
 Contributing
 ============
-.. include:: ../../CONTRIBUTING.rst
+
+.. include:: ../../../CONTRIBUTING.rst
 
 As your code is subject to the `review guidelines <./review-guidelines.html>`_,
 please take the time to familiarize yourself with those guidelines.

doc/source/contributor/index.rst

@@ -0,0 +1,36 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Neutron lib devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+
+Contributor Guide
+=================
+
+In the Contributor Guide, you will find information on the Neutron Library
+components and in how to use them, from a development standpoint.
+
+.. toctree::
+   :maxdepth: 2
+
+   conventions
+   review-guidelines
+   contributing
+   releasing
+   internals

doc/source/contributor/internals.rst

@@ -19,16 +19,10 @@
       '''''''  Heading 4
       (Avoid deeper levels because they do not render well.)
 
-
+=====================
-Developer Guide
-===============
-
-In the Developer Guide, you will find information on the Neutron Library
-components and in how to use them, from a development standpoint.
-
-
 Neutron Lib Internals
----------------------
+=====================
+
 .. toctree::
    :maxdepth: 3
 
@@ -37,20 +31,3 @@ Neutron Lib Internals
    api_converters
    api_validators
    callbacks
-
-
-Module Reference
-----------------
-.. toctree::
-   :maxdepth: 3
-
-.. todo::
-
-    Add in all the big modules as automodule indexes.
-
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`search`

doc/source/index.rst

@@ -11,8 +11,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-Welcome to Neutron Lib developer documentation!
+Welcome to Neutron Lib documentation!
-===============================================
+=====================================
 
 Neutron-lib is an OpenStack library project used by Neutron, Advanced Services,
 and third-party projects that aims to provide common functionality across all
@@ -39,24 +39,10 @@ The `Neutron Development wiki`_ is also a good resource for new contributors.
 
 Enjoy!
 
-
-Programming HowTos and Tutorials
---------------------------------
 .. toctree::
-    :maxdepth: 3
+   :maxdepth: 2
 
-    conventions
+   install/index
-    installation
+   user/index
-    usage
+   contributor/index
-    review-guidelines
+   reference/index
-    contributing
-    releasing
-
-
-Developer Docs
-==============
-
-.. toctree::
-   :maxdepth: 1
-
-   devref/index

doc/source/reference/index.rst

@@ -0,0 +1,34 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Neutron lib devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+================
+Module Reference
+================
+
+.. toctree::
+   :maxdepth: 1
+
+.. todo::
+
+   Add in all the big modules as automodule indexes.
+
+* :ref:`genindex`
+* :ref:`search`

doc/source/user/hacking.rst

@@ -1,14 +1,6 @@
-========
+==============
-Usage
-========
-
-To use neutron-lib in a project::
-
-    import neutron_lib
-
-
 Hacking Checks
---------------
+==============
 
 The ``neutron_lib.hacking`` package implements a number of public
 `hacking checks <https://github.com/openstack-dev/hacking>`_ intended to help

doc/source/user/index.rst

@@ -0,0 +1,8 @@
+=====
+Usage
+=====
+
+.. toctree::
+   :maxdepth: 2
+
+   hacking