From 050974ddc4ec2e9972431a1939728ee8b00ba0de Mon Sep 17 00:00:00 2001 From: Elena Ezhova Date: Wed, 10 Jun 2015 16:42:57 +0300 Subject: [PATCH] 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 +- doc/source/api.rst | 12 ---------- doc/source/api/eventlet_backdoor.rst | 7 ++++++ doc/source/api/loopingcall.rst | 8 +++++++ doc/source/api/periodic_task.rst | 8 +++++++ doc/source/api/service.rst | 8 +++++++ doc/source/api/sslutils.rst | 8 +++++++ doc/source/api/systemd.rst | 8 +++++++ doc/source/api/threadgroup.rst | 8 +++++++ doc/source/index.rst | 33 ++++++++++++++++--------- doc/source/usage.rst | 36 ++++++++++++++++++++++++++++ 11 files changed, 114 insertions(+), 24 deletions(-) delete mode 100644 doc/source/api.rst create mode 100644 doc/source/api/eventlet_backdoor.rst create mode 100644 doc/source/api/loopingcall.rst create mode 100644 doc/source/api/periodic_task.rst create mode 100644 doc/source/api/service.rst create mode 100644 doc/source/api/sslutils.rst create mode 100644 doc/source/api/systemd.rst create mode 100644 doc/source/api/threadgroup.rst diff --git a/README.rst b/README.rst index 7e14f697..921448d3 100644 --- a/README.rst +++ b/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 diff --git a/doc/source/api.rst b/doc/source/api.rst deleted file mode 100644 index 971225e7..00000000 --- a/doc/source/api.rst +++ /dev/null @@ -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). diff --git a/doc/source/api/eventlet_backdoor.rst b/doc/source/api/eventlet_backdoor.rst new file mode 100644 index 00000000..45158ace --- /dev/null +++ b/doc/source/api/eventlet_backdoor.rst @@ -0,0 +1,7 @@ +================== + eventlet_backdoor +================== + +.. automodule:: oslo_service.eventlet_backdoor + :members: + :show-inheritance: diff --git a/doc/source/api/loopingcall.rst b/doc/source/api/loopingcall.rst new file mode 100644 index 00000000..9fec61f8 --- /dev/null +++ b/doc/source/api/loopingcall.rst @@ -0,0 +1,8 @@ +============= + loopingcall +============= + +.. automodule:: oslo_service.loopingcall + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/api/periodic_task.rst b/doc/source/api/periodic_task.rst new file mode 100644 index 00000000..e986f999 --- /dev/null +++ b/doc/source/api/periodic_task.rst @@ -0,0 +1,8 @@ +============== + periodic_task +============== + +.. automodule:: oslo_service.periodic_task + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/api/service.rst b/doc/source/api/service.rst new file mode 100644 index 00000000..316c4554 --- /dev/null +++ b/doc/source/api/service.rst @@ -0,0 +1,8 @@ +========= + service +========= + +.. automodule:: oslo_service.service + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/api/sslutils.rst b/doc/source/api/sslutils.rst new file mode 100644 index 00000000..bb0cdd16 --- /dev/null +++ b/doc/source/api/sslutils.rst @@ -0,0 +1,8 @@ +========== + sslutils +========== + +.. automodule:: oslo_service.sslutils + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/api/systemd.rst b/doc/source/api/systemd.rst new file mode 100644 index 00000000..fd234135 --- /dev/null +++ b/doc/source/api/systemd.rst @@ -0,0 +1,8 @@ +========= + systemd +========= + +.. automodule:: oslo_service.systemd + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/api/threadgroup.rst b/doc/source/api/threadgroup.rst new file mode 100644 index 00000000..38d99c98 --- /dev/null +++ b/doc/source/api/threadgroup.rst @@ -0,0 +1,8 @@ +============= + threadgroup +============= + +.. automodule:: oslo_service.threadgroup + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/index.rst b/doc/source/index.rst index 468ffe02..6ac47c04 100644 --- a/doc/source/index.rst +++ b/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 diff --git a/doc/source/usage.rst b/doc/source/usage.rst index a8808085..945bdd73 100644 --- a/doc/source/usage.rst +++ b/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)