From 21de4a7c510ff0356c5c557d4c50bbc755052785 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Sat, 1 Jul 2017 19:43:28 +0900 Subject: [PATCH] rearrange existing documentation to fit the new standard layout Change-Id: I920d02fd4843c21f41c57f0effed31441ec5998e --- CONTRIBUTING.rst | 9 ++-- .../{opts.rst => configuration/index.rst} | 0 doc/source/contributing.rst | 5 --- doc/source/contributor/index.rst | 5 +++ doc/source/history.rst | 1 - doc/source/index.rst | 42 ++++--------------- .../{installation.rst => install/index.rst} | 0 .../{api => reference}/eventlet_backdoor.rst | 1 + doc/source/reference/index.rst | 14 +++++++ doc/source/{api => reference}/loopingcall.rst | 0 .../{api => reference}/periodic_task.rst | 0 doc/source/{api => reference}/service.rst | 0 doc/source/{api => reference}/sslutils.rst | 0 doc/source/{api => reference}/systemd.rst | 0 doc/source/{api => reference}/threadgroup.rst | 0 doc/source/user/history.rst | 1 + doc/source/user/index.rst | 14 +++++++ doc/source/{ => user}/usage.rst | 26 ++++++------ 18 files changed, 60 insertions(+), 58 deletions(-) rename doc/source/{opts.rst => configuration/index.rst} (100%) delete mode 100644 doc/source/contributing.rst create mode 100644 doc/source/contributor/index.rst delete mode 100644 doc/source/history.rst rename doc/source/{installation.rst => install/index.rst} (100%) rename doc/source/{api => reference}/eventlet_backdoor.rst (88%) create mode 100644 doc/source/reference/index.rst rename doc/source/{api => reference}/loopingcall.rst (100%) rename doc/source/{api => reference}/periodic_task.rst (100%) rename doc/source/{api => reference}/service.rst (100%) rename doc/source/{api => reference}/sslutils.rst (100%) rename doc/source/{api => reference}/systemd.rst (100%) rename doc/source/{api => reference}/threadgroup.rst (100%) create mode 100644 doc/source/user/history.rst create mode 100644 doc/source/user/index.rst rename doc/source/{ => user}/usage.rst (92%) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 617ba44c..d8c78989 100644 --- a/CONTRIBUTING.rst +++ b/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 diff --git a/doc/source/opts.rst b/doc/source/configuration/index.rst similarity index 100% rename from doc/source/opts.rst rename to doc/source/configuration/index.rst diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 2ca75d1b..00000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,5 +0,0 @@ -============== - Contributing -============== - -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 00000000..3d4ceb40 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,5 @@ +============ +Contributing +============ + +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/history.rst b/doc/source/history.rst deleted file mode 100644 index 69ed4fe6..00000000 --- a/doc/source/history.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../ChangeLog diff --git a/doc/source/index.rst b/doc/source/index.rst index df539397..6fee3d6d 100644 --- a/doc/source/index.rst +++ b/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 diff --git a/doc/source/installation.rst b/doc/source/install/index.rst similarity index 100% rename from doc/source/installation.rst rename to doc/source/install/index.rst diff --git a/doc/source/api/eventlet_backdoor.rst b/doc/source/reference/eventlet_backdoor.rst similarity index 88% rename from doc/source/api/eventlet_backdoor.rst rename to doc/source/reference/eventlet_backdoor.rst index 45158ace..c60dc47f 100644 --- a/doc/source/api/eventlet_backdoor.rst +++ b/doc/source/reference/eventlet_backdoor.rst @@ -4,4 +4,5 @@ .. automodule:: oslo_service.eventlet_backdoor :members: + :undoc-members: :show-inheritance: diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 00000000..17dedc47 --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,14 @@ +============= +API Reference +============= + +.. toctree:: + :maxdepth: 1 + + eventlet_backdoor + loopingcall + periodic_task + service + sslutils + systemd + threadgroup diff --git a/doc/source/api/loopingcall.rst b/doc/source/reference/loopingcall.rst similarity index 100% rename from doc/source/api/loopingcall.rst rename to doc/source/reference/loopingcall.rst diff --git a/doc/source/api/periodic_task.rst b/doc/source/reference/periodic_task.rst similarity index 100% rename from doc/source/api/periodic_task.rst rename to doc/source/reference/periodic_task.rst diff --git a/doc/source/api/service.rst b/doc/source/reference/service.rst similarity index 100% rename from doc/source/api/service.rst rename to doc/source/reference/service.rst diff --git a/doc/source/api/sslutils.rst b/doc/source/reference/sslutils.rst similarity index 100% rename from doc/source/api/sslutils.rst rename to doc/source/reference/sslutils.rst diff --git a/doc/source/api/systemd.rst b/doc/source/reference/systemd.rst similarity index 100% rename from doc/source/api/systemd.rst rename to doc/source/reference/systemd.rst diff --git a/doc/source/api/threadgroup.rst b/doc/source/reference/threadgroup.rst similarity index 100% rename from doc/source/api/threadgroup.rst rename to doc/source/reference/threadgroup.rst diff --git a/doc/source/user/history.rst b/doc/source/user/history.rst new file mode 100644 index 00000000..f69be70b --- /dev/null +++ b/doc/source/user/history.rst @@ -0,0 +1 @@ +.. include:: ../../../ChangeLog diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 00000000..4209e783 --- /dev/null +++ b/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 diff --git a/doc/source/usage.rst b/doc/source/user/usage.rst similarity index 92% rename from doc/source/usage.rst rename to doc/source/user/usage.rst index 01df6891..60c6ac82 100644 --- a/doc/source/usage.rst +++ b/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