rearrange existing documentation to fit the new standard layout

Change-Id: I920d02fd4843c21f41c57f0effed31441ec5998e

CONTRIBUTING.rst

@@ -1,16 +1,13 @@
 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
+http://docs.openstack.org/infra/manual/developers.html
 
 Once those steps have been completed, changes to OpenStack
 should be submitted for review via the Gerrit tool, following
 the workflow documented at:
-
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
+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/oslo.service
+https://bugs.launchpad.net/oslo.service

doc/source/contributing.rst

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

doc/source/contributor/index.rst

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

doc/source/history.rst

@@ -1 +0,0 @@
-.. include:: ../../ChangeLog

doc/source/index.rst

@@ -1,6 +1,6 @@
-========================================================
- oslo.service -- Library for running OpenStack services
-========================================================
+======================================================
+oslo.service -- Library for running OpenStack services
+======================================================
 
 oslo.service provides a framework for defining new long-running
 services using the patterns established by other OpenStack
@@ -11,38 +11,14 @@ operations, interacting with systemd, etc.
 .. toctree::
    :maxdepth: 2
 
-   installation
-   usage
-   opts
-   contributing
+   install/index
+   user/index
+   configuration/index
+   reference/index
+   contributor/index
 
-API Documentation
-=================
-
-.. toctree::
-   :maxdepth: 2
-
-   api/eventlet_backdoor
-   api/loopingcall
-   api/periodic_task
-   api/service
-   api/sslutils
-   api/systemd
-   api/threadgroup
-
-Release Notes
-=============
-
-.. toctree::
-   :maxdepth: 1
-
-   history
-
-Indices and tables
-==================
+.. rubric:: Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
-.. _oslo: https://wiki.openstack.org/wiki/Oslo

doc/source/reference/eventlet_backdoor.rst

@@ -4,4 +4,5 @@
 
 .. automodule:: oslo_service.eventlet_backdoor
    :members:
+   :undoc-members:
    :show-inheritance:

doc/source/reference/index.rst

@@ -0,0 +1,14 @@
+=============
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   eventlet_backdoor
+   loopingcall
+   periodic_task
+   service
+   sslutils
+   systemd
+   threadgroup

doc/source/user/history.rst

@@ -0,0 +1 @@
+.. include:: ../../../ChangeLog

doc/source/user/index.rst

@@ -0,0 +1,14 @@
+==================
+Using oslo.service
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+
+.. history contains a lot of sections, toctree with maxdepth 1 is used.
+.. toctree::
+   :maxdepth: 1
+
+   history

doc/source/user/usage.rst

@@ -1,6 +1,6 @@
-=======
- Usage
-=======
+=====
+Usage
+=====
 
 To use oslo.service in a project::
 
@@ -23,7 +23,7 @@ configuration object:
 * :func:`~oslo_service.sslutils.wrap`
 
 When using service from oslo-incubator
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
@@ -32,7 +32,7 @@ When using service from oslo-incubator
     launcher = service.launch(service, workers=2)
 
 When using oslo.service
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
@@ -43,7 +43,7 @@ When using oslo.service
     launcher = service.launch(CONF, service, workers=2)
 
 Using oslo.service with oslo-config-generator
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``oslo.service`` provides several entry points to generate a configuration
 files.
@@ -87,15 +87,15 @@ Launchers
 
 oslo_service.service module provides two launchers for running services:
 
-    * :py:class:`oslo_service.service.ServiceLauncher` - used for
-      running one or more service in a parent process.
-    * :py:class:`oslo_service.service.ProcessLauncher` - forks a given
-      number of workers in which service(s) are then started.
+* :py:class:`oslo_service.service.ServiceLauncher` - used for
+  running one or more service in a parent process.
+* :py:class:`oslo_service.service.ProcessLauncher` - forks a given
+  number of workers in which service(s) are then started.
 
 It is possible to initialize whatever launcher is needed and then
 launch a service using it.
 
-::
+.. code-block:: python
 
     from oslo_config import cfg
     from oslo_service import service
@@ -114,7 +114,7 @@ automatically pick an appropriate launcher based on a number of workers that
 are passed to it (ServiceLauncher in case workers=1 or None and
 ProcessLauncher in other case).
 
-::
+.. code-block:: python
 
     from oslo_config import cfg
     from oslo_service import service
@@ -154,7 +154,7 @@ spawned. Thus, SIGHUP can be used for changing config options on the go.
 Below is the example of a service with a reset method that allows reloading
 logging options by sending a SIGHUP.
 
-::
+.. code-block:: python
 
     from oslo_config import cfg
     from oslo_log import log as logging