Add proper documentation

Replace the cookiecutter docs with actual docs that describe the api
and explain how to use the project.

Change-Id: Ica2c76809d22a387993da1e19c75b33f9fe263d4
This commit is contained in:
Ben Nemec 2018-09-17 22:07:36 +00:00
parent 587b29fffd
commit 32c53f2992
4 changed files with 55 additions and 10 deletions

View File

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

View File

@ -2,7 +2,12 @@
oslo.upgradecheck oslo.upgradecheck
=================== ===================
Common code for writing OpenStack upgrade checks Common code for writing OpenStack upgrade checks.
This project can be used to assist with the implementation of a
``$SERVICE-status`` command that responds to parameters of ``upgrade check``
by running upgrade check functions on the existing installation. For further
details see :doc:`usage`.
Contents Contents
======== ========

View File

@ -2,6 +2,43 @@
Usage Usage
======= =======
To use oslo.upgradecheck in a project:: See the module ``oslo_upgradecheck.__main__`` for an example of how to use this
project.
import oslo_upgradecheck Each consuming project should create a class that inherits from
:class:`oslo_upgradecheck.upgradecheck.UpgradeCommands` and implement check
methods on it. Those check methods should then be added to the
``_upgrade_checks`` tuple so they will be run when the
:meth:`oslo_upgradecheck.upgradecheck.UpgradeCommands.check` method is
called. For example::
from oslo_upgradecheck import upgradecheck
class ProjectSpecificUpgradeCommands(upgradecheck.UpgradeCommands):
def an_upgrade_check(self):
if everything_is_awesome():
return upgradecheck.UpgradeCheckResult(
upgradecheck.UpgradeCheckCode.SUCCESS, 'Success details')
else:
return upgradecheck.UpgradeCheckResult(
upgradecheck.UpgradeCheckCode.FAILURE, 'Failure details')
_upgrade_checks = (('Awesome upgrade check', an_upgrade_check))
oslo.upgradecheck also includes a basic implementation of command line argument
handling that can be used to provide the minimum processing needed to implement
a ``$SERVICE-status upgrade check`` command. To make use of it, write a method
that creates an instance of the class created above, then pass that class's
``check`` method into :func:`oslo_upgradecheck.upgradecheck.main`. For
example::
def main():
inst = ProjectSpecificUpgradeCommands()
return upgradecheck.main(inst.check)
The entry point for the ``$SERVICE-status`` command should then point at this
method.
Alternatively, if a project has its own CLI code that it would prefer to reuse,
it simply needs to ensure that the ``inst.check`` method is called when the
``upgrade check`` parameters are passed to the ``$SERVICE-status`` command.

View File

@ -64,6 +64,12 @@ class UpgradeCheckResult(object):
class UpgradeCommands(object): class UpgradeCommands(object):
"""Base class for upgrade checks
This class should be inherited by a class in each project that provides
the actual checks. Those checks should be added to the _upgrade_checks
class member so that they are run when the ``check`` method is called.
"""
_upgrade_checks = () _upgrade_checks = ()
def _get_details(self, upgrade_check_result): def _get_details(self, upgrade_check_result):