From 15a5d69812ef0c565bcf042a4e2c46cec38f2f04 Mon Sep 17 00:00:00 2001
From: Ben Nemec <bnemec@redhat.com>
Date: Mon, 17 Sep 2018 22:07:36 +0000
Subject: [PATCH] Add proper documentation

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

Change-Id: Ica2c76809d22a387993da1e19c75b33f9fe263d4
---
 doc/source/api.rst                | 11 +++------
 doc/source/index.rst              |  9 ++++++-
 doc/source/usage.rst              | 41 +++++++++++++++++++++++++++++--
 oslo_upgradecheck/upgradecheck.py |  6 +++++
 4 files changed, 57 insertions(+), 10 deletions(-)

diff --git a/doc/source/api.rst b/doc/source/api.rst
index 971225e..20b5cbc 100644
--- a/doc/source/api.rst
+++ b/doc/source/api.rst
@@ -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:
diff --git a/doc/source/index.rst b/doc/source/index.rst
index a029a1a..c7ea142 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -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
 ========
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index ae3622b..41c6ca5 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -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.
diff --git a/oslo_upgradecheck/upgradecheck.py b/oslo_upgradecheck/upgradecheck.py
index f28bce1..858a254 100644
--- a/oslo_upgradecheck/upgradecheck.py
+++ b/oslo_upgradecheck/upgradecheck.py
@@ -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):