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:
parent
2458b6a561
commit
15a5d69812
@ -2,11 +2,8 @@
|
||||
API
|
||||
=====
|
||||
|
||||
.. Use autodoc directives to describe the *public* modules and classes
|
||||
in the library.
|
||||
upgradecheck module
|
||||
-------------------
|
||||
|
||||
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).
|
||||
.. automodule:: oslo_upgradecheck.upgradecheck
|
||||
:members:
|
||||
|
@ -2,7 +2,14 @@
|
||||
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` and the `Nova documentation on upgrade checks`_.
|
||||
|
||||
.. _`Nova documentation on upgrade checks`: https://docs.openstack.org/nova/latest/reference/upgrade-checks.html
|
||||
|
||||
Contents
|
||||
========
|
||||
|
@ -2,6 +2,43 @@
|
||||
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.
|
||||
|
@ -64,6 +64,12 @@ class UpgradeCheckResult(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 = ()
|
||||
|
||||
def _get_details(self, upgrade_check_result):
|
||||
|
Loading…
x
Reference in New Issue
Block a user