Add oslo.service documentation

Updated library's description in README.rst with one that is used
on Launchpad and PyPi.

Added API documentation for oslo_serive modules.

Updated usage documentation with information with the adoption
guidelines.

DocImpact
bp graduate-oslo-service

Change-Id: I4beaf30f47fb007b311e5a45ed7953c0f8df97c3

README.rst

@@ -2,7 +2,7 @@
 oslo.service
 ===================================
 
-oslo.service library
+Library for running OpenStack services
 
 * Free software: Apache license
 * Documentation: http://docs.openstack.org/developer/oslo.service

doc/source/api.rst

@@ -1,12 +0,0 @@
-=====
- API
-=====
-
-.. Use autodoc directives to describe the *public* modules and classes
-   in the library.
-
-   If the modules are completely unrelated, create an api subdirectory
-   and use a separate file for each (see oslo.utils).
-
-   If there is only one submodule, a single api.rst file like this
-   sufficient (see oslo.i18n).

doc/source/api/eventlet_backdoor.rst

@@ -0,0 +1,7 @@
+==================
+ eventlet_backdoor
+==================
+
+.. automodule:: oslo_service.eventlet_backdoor
+   :members:
+   :show-inheritance:

doc/source/api/loopingcall.rst

@@ -0,0 +1,8 @@
+=============
+ loopingcall
+=============
+
+.. automodule:: oslo_service.loopingcall
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/periodic_task.rst

@@ -0,0 +1,8 @@
+==============
+ periodic_task
+==============
+
+.. automodule:: oslo_service.periodic_task
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/service.rst

@@ -0,0 +1,8 @@
+=========
+ service
+=========
+
+.. automodule:: oslo_service.service
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/sslutils.rst

@@ -0,0 +1,8 @@
+==========
+ sslutils
+==========
+
+.. automodule:: oslo_service.sslutils
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/systemd.rst

@@ -0,0 +1,8 @@
+=========
+ systemd
+=========
+
+.. automodule:: oslo_service.systemd
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/threadgroup.rst

@@ -0,0 +1,8 @@
+=============
+ threadgroup
+=============
+
+.. automodule:: oslo_service.threadgroup
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/index.rst

@@ -1,20 +1,30 @@
-==============
- oslo.service
-==============
+========================================
+Welcome to oslo.service's documentation!
+========================================
 
-oslo.service library
+Library for running OpenStack services
 
-Contents
-========
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   usage
+   contributing
+   history
+
+API Documentation
+=================
 
 .. toctree::
    :maxdepth: 2
 
-   installation
-   api
-   usage
-   contributing
-   history
+   api/eventlet_backdoor
+   api/loopingcall
+   api/periodic_task
+   api/service
+   api/sslutils
+   api/systemd
+   api/threadgroup
 
 Indices and tables
 ==================
@@ -23,3 +33,4 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+.. _oslo: https://wiki.openstack.org/wiki/Oslo

doc/source/usage.rst

@@ -5,3 +5,39 @@
 To use oslo.service in a project::
 
     import oslo_service
+
+Migrating to oslo.service
+=========================
+
+The ``oslo.service`` library no longer assumes a global configuration object is
+available. Instead the following functions and classes have been
+changed to expect the consuming application to pass in an ``oslo.config``
+configuration object:
+
+* :func:`~oslo_service.eventlet_backdoor.initialize_if_enabled`
+* :py:class:`oslo_service.periodic_task.PeriodicTasks`
+* :func:`~oslo_service.service.launch`
+* :py:class:`oslo_service.service.ProcessLauncher`
+* :py:class:`oslo_service.service.ServiceLauncher`
+* :func:`~oslo_service.sslutils.is_enabled`
+* :func:`~oslo_service.sslutils.wrap`
+
+When using service from oslo-incubator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    from foo.openstack.common import service
+
+    launcher = service.launch(service, workers=2)
+
+When using oslo.service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    from oslo_config import cfg
+    from oslo_service import service
+
+    CONF = cfg.CONF
+    launcher = service.launch(CONF, service, workers=2)