From 9014fdd8d4851be369ad4f0ced2cb8c26f7f345a Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 7 Jul 2017 14:26:34 -0400 Subject: rearrange existing documentation to follow the new layout standard Change-Id: I79d7b97c7e9395f75fa158d870485853418a4db7 Signed-off-by: Doug Hellmann --- doc/source/api/fixture.lockutils.rst | 8 ---- doc/source/api/index.rst | 8 ---- doc/source/api/lockutils.rst | 8 ---- doc/source/api/opts.rst | 8 ---- doc/source/api/processutils.rst | 8 ---- doc/source/api/watchdog.rst | 8 ---- doc/source/configuration/index.rst | 8 ++++ doc/source/contributing.rst | 5 -- doc/source/contributor/contributing.rst | 5 ++ doc/source/contributor/history.rst | 1 + doc/source/contributor/index.rst | 9 ++++ doc/source/history.rst | 1 - doc/source/index.rst | 25 ++-------- doc/source/install/index.rst | 12 +++++ doc/source/installation.rst | 12 ----- doc/source/opts.rst | 8 ---- doc/source/reference/fixture.lockutils.rst | 8 ++++ doc/source/reference/index.rst | 12 +++++ doc/source/reference/lockutils.rst | 8 ++++ doc/source/reference/opts.rst | 8 ++++ doc/source/reference/processutils.rst | 8 ++++ doc/source/reference/watchdog.rst | 8 ++++ doc/source/usage.rst | 74 ------------------------------ doc/source/user/index.rst | 74 ++++++++++++++++++++++++++++++ 24 files changed, 166 insertions(+), 168 deletions(-) delete mode 100644 doc/source/api/fixture.lockutils.rst delete mode 100644 doc/source/api/index.rst delete mode 100644 doc/source/api/lockutils.rst delete mode 100644 doc/source/api/opts.rst delete mode 100644 doc/source/api/processutils.rst delete mode 100644 doc/source/api/watchdog.rst create mode 100644 doc/source/configuration/index.rst delete mode 100644 doc/source/contributing.rst create mode 100644 doc/source/contributor/contributing.rst create mode 100644 doc/source/contributor/history.rst create mode 100644 doc/source/contributor/index.rst delete mode 100644 doc/source/history.rst create mode 100644 doc/source/install/index.rst delete mode 100644 doc/source/installation.rst delete mode 100644 doc/source/opts.rst create mode 100644 doc/source/reference/fixture.lockutils.rst create mode 100644 doc/source/reference/index.rst create mode 100644 doc/source/reference/lockutils.rst create mode 100644 doc/source/reference/opts.rst create mode 100644 doc/source/reference/processutils.rst create mode 100644 doc/source/reference/watchdog.rst delete mode 100644 doc/source/usage.rst create mode 100644 doc/source/user/index.rst (limited to 'doc') diff --git a/doc/source/api/fixture.lockutils.rst b/doc/source/api/fixture.lockutils.rst deleted file mode 100644 index 8f82f40..0000000 --- a/doc/source/api/fixture.lockutils.rst +++ /dev/null @@ -1,8 +0,0 @@ -=========================================== - :mod:`oslo_concurrency.fixture.lockutils` -=========================================== - -.. automodule:: oslo_concurrency.fixture.lockutils - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst deleted file mode 100644 index 2ee39d8..0000000 --- a/doc/source/api/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. toctree:: - :maxdepth: 1 - - fixture.lockutils - lockutils - opts - processutils - watchdog diff --git a/doc/source/api/lockutils.rst b/doc/source/api/lockutils.rst deleted file mode 100644 index 76a37fa..0000000 --- a/doc/source/api/lockutils.rst +++ /dev/null @@ -1,8 +0,0 @@ -=================================== - :mod:`oslo_concurrency.lockutils` -=================================== - -.. automodule:: oslo_concurrency.lockutils - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/api/opts.rst b/doc/source/api/opts.rst deleted file mode 100644 index 8972b27..0000000 --- a/doc/source/api/opts.rst +++ /dev/null @@ -1,8 +0,0 @@ -============================== - :mod:`oslo_concurrency.opts` -============================== - -.. automodule:: oslo_concurrency.opts - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/api/processutils.rst b/doc/source/api/processutils.rst deleted file mode 100644 index 787095c..0000000 --- a/doc/source/api/processutils.rst +++ /dev/null @@ -1,8 +0,0 @@ -====================================== - :mod:`oslo_concurrency.processutils` -====================================== - -.. automodule:: oslo_concurrency.processutils - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/api/watchdog.rst b/doc/source/api/watchdog.rst deleted file mode 100644 index feccaeb..0000000 --- a/doc/source/api/watchdog.rst +++ /dev/null @@ -1,8 +0,0 @@ -================================== - :mod:`oslo_concurrency.watchdog` -================================== - -.. automodule:: oslo_concurrency.watchdog - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 0000000..27ee4fb --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,8 @@ +======================= + Configuration Options +======================= + +oslo.concurrency uses oslo.config to define and manage configuration options +to allow the deployer to control how an application uses this library. + +.. show-options:: oslo.concurrency diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 2ca75d1..0000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,5 +0,0 @@ -============== - Contributing -============== - -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000..ed5290b --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,5 @@ +============== + Contributing +============== + +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/contributor/history.rst b/doc/source/contributor/history.rst new file mode 100644 index 0000000..f69be70 --- /dev/null +++ b/doc/source/contributor/history.rst @@ -0,0 +1 @@ +.. include:: ../../../ChangeLog diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000..ae57822 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,9 @@ +===================== + Contributor's Guide +===================== + +.. toctree:: + :maxdepth: 2 + + contributing + history diff --git a/doc/source/history.rst b/doc/source/history.rst deleted file mode 100644 index 69ed4fe..0000000 --- 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 4ff4a70..f2297d1 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,26 +9,11 @@ external processes. .. toctree:: :maxdepth: 1 - installation - usage - opts - contributing - -API Documentation -================= - -.. toctree:: - :maxdepth: 1 - - api/index - -Release Notes -============= - -.. toctree:: - :maxdepth: 1 - - history + install/index + user/index + configuration/index + contributor/index + reference/index Indices and tables ================== diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 0000000..0f63912 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,12 @@ +============ +Installation +============ + +At the command line:: + + $ pip install oslo.concurrency + +Or, if you have virtualenvwrapper installed:: + + $ mkvirtualenv oslo.concurrency + $ pip install oslo.concurrency \ No newline at end of file diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index 0f63912..0000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,12 +0,0 @@ -============ -Installation -============ - -At the command line:: - - $ pip install oslo.concurrency - -Or, if you have virtualenvwrapper installed:: - - $ mkvirtualenv oslo.concurrency - $ pip install oslo.concurrency \ No newline at end of file diff --git a/doc/source/opts.rst b/doc/source/opts.rst deleted file mode 100644 index 27ee4fb..0000000 --- a/doc/source/opts.rst +++ /dev/null @@ -1,8 +0,0 @@ -======================= - Configuration Options -======================= - -oslo.concurrency uses oslo.config to define and manage configuration options -to allow the deployer to control how an application uses this library. - -.. show-options:: oslo.concurrency diff --git a/doc/source/reference/fixture.lockutils.rst b/doc/source/reference/fixture.lockutils.rst new file mode 100644 index 0000000..8f82f40 --- /dev/null +++ b/doc/source/reference/fixture.lockutils.rst @@ -0,0 +1,8 @@ +=========================================== + :mod:`oslo_concurrency.fixture.lockutils` +=========================================== + +.. automodule:: oslo_concurrency.fixture.lockutils + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 0000000..60abf32 --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,12 @@ +=============== + API Reference +=============== + +.. toctree:: + :maxdepth: 1 + + fixture.lockutils + lockutils + opts + processutils + watchdog diff --git a/doc/source/reference/lockutils.rst b/doc/source/reference/lockutils.rst new file mode 100644 index 0000000..76a37fa --- /dev/null +++ b/doc/source/reference/lockutils.rst @@ -0,0 +1,8 @@ +=================================== + :mod:`oslo_concurrency.lockutils` +=================================== + +.. automodule:: oslo_concurrency.lockutils + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/reference/opts.rst b/doc/source/reference/opts.rst new file mode 100644 index 0000000..8972b27 --- /dev/null +++ b/doc/source/reference/opts.rst @@ -0,0 +1,8 @@ +============================== + :mod:`oslo_concurrency.opts` +============================== + +.. automodule:: oslo_concurrency.opts + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/reference/processutils.rst b/doc/source/reference/processutils.rst new file mode 100644 index 0000000..787095c --- /dev/null +++ b/doc/source/reference/processutils.rst @@ -0,0 +1,8 @@ +====================================== + :mod:`oslo_concurrency.processutils` +====================================== + +.. automodule:: oslo_concurrency.processutils + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/reference/watchdog.rst b/doc/source/reference/watchdog.rst new file mode 100644 index 0000000..feccaeb --- /dev/null +++ b/doc/source/reference/watchdog.rst @@ -0,0 +1,8 @@ +================================== + :mod:`oslo_concurrency.watchdog` +================================== + +.. automodule:: oslo_concurrency.watchdog + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index dd8ba98..0000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,74 +0,0 @@ -======= - Usage -======= - -To use oslo.concurrency in a project, import the relevant module. For -example:: - - from oslo_concurrency import lockutils - from oslo_concurrency import processutils - -.. seealso:: - - * :doc:`API Documentation ` - -Locking a function (local to a process) -======================================= - -To ensure that a function (which is not thread safe) is only used in -a thread safe manner (typically such type of function should be refactored -to avoid this problem but if not then the following can help):: - - @lockutils.synchronized('not_thread_safe') - def not_thread_safe(): - pass - -Once decorated later callers of this function will be able to call into -this method and the contract that two threads will **not** enter this -function at the same time will be upheld. Make sure that the names of the -locks used are carefully chosen (typically by namespacing them to your -app so that other apps will not chose the same names). - -Locking a function (local to a process as well as across process) -================================================================= - -To ensure that a function (which is not thread safe **or** multi-process -safe) is only used in a safe manner (typically such type of function should -be refactored to avoid this problem but if not then the following can help):: - - @lockutils.synchronized('not_thread_process_safe', external=True) - def not_thread_process_safe(): - pass - -Once decorated later callers of this function will be able to call into -this method and the contract that two threads (or any two processes) -will **not** enter this function at the same time will be upheld. Make -sure that the names of the locks used are carefully chosen (typically by -namespacing them to your app so that other apps will not chose the same -names). - -Common ways to prefix/namespace the synchronized decorator -========================================================== - -Since it is **highly** recommended to prefix (or namespace) the usage -of the synchronized there are a few helpers that can make this much easier -to achieve. - -An example is:: - - myapp_synchronized = lockutils.synchronized_with_prefix("myapp") - -Then further usage of the ``lockutils.synchronized`` would instead now use -this decorator created above instead of using ``lockutils.synchronized`` -directly. - -Command Line Wrapper -==================== - -``oslo.concurrency`` includes a command line tool for use in test jobs -that need the environment variable :envvar:`OSLO_LOCK_PATH` set. To -use it, prefix the command to be run with -:command:`lockutils-wrapper`. For example:: - - $ lockutils-wrapper env | grep OSLO_LOCK_PATH - OSLO_LOCK_PATH=/tmp/tmpbFHK45 diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 0000000..1867faf --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,74 @@ +======= + Usage +======= + +To use oslo.concurrency in a project, import the relevant module. For +example:: + + from oslo_concurrency import lockutils + from oslo_concurrency import processutils + +.. seealso:: + + * :doc:`API Documentation <../reference/index>` + +Locking a function (local to a process) +======================================= + +To ensure that a function (which is not thread safe) is only used in +a thread safe manner (typically such type of function should be refactored +to avoid this problem but if not then the following can help):: + + @lockutils.synchronized('not_thread_safe') + def not_thread_safe(): + pass + +Once decorated later callers of this function will be able to call into +this method and the contract that two threads will **not** enter this +function at the same time will be upheld. Make sure that the names of the +locks used are carefully chosen (typically by namespacing them to your +app so that other apps will not chose the same names). + +Locking a function (local to a process as well as across process) +================================================================= + +To ensure that a function (which is not thread safe **or** multi-process +safe) is only used in a safe manner (typically such type of function should +be refactored to avoid this problem but if not then the following can help):: + + @lockutils.synchronized('not_thread_process_safe', external=True) + def not_thread_process_safe(): + pass + +Once decorated later callers of this function will be able to call into +this method and the contract that two threads (or any two processes) +will **not** enter this function at the same time will be upheld. Make +sure that the names of the locks used are carefully chosen (typically by +namespacing them to your app so that other apps will not chose the same +names). + +Common ways to prefix/namespace the synchronized decorator +========================================================== + +Since it is **highly** recommended to prefix (or namespace) the usage +of the synchronized there are a few helpers that can make this much easier +to achieve. + +An example is:: + + myapp_synchronized = lockutils.synchronized_with_prefix("myapp") + +Then further usage of the ``lockutils.synchronized`` would instead now use +this decorator created above instead of using ``lockutils.synchronized`` +directly. + +Command Line Wrapper +==================== + +``oslo.concurrency`` includes a command line tool for use in test jobs +that need the environment variable :envvar:`OSLO_LOCK_PATH` set. To +use it, prefix the command to be run with +:command:`lockutils-wrapper`. For example:: + + $ lockutils-wrapper env | grep OSLO_LOCK_PATH + OSLO_LOCK_PATH=/tmp/tmpbFHK45 -- cgit v1.2.1