Move example implementation to docs

This moves the example implementation from __main__.py to the docs
tree so it isn't confused for production code. A unit test is also
added to ensure that the example is kept up to date with any changes
in the API.

Change-Id: I92aa685f410ae0e56d5d55a15812edaae83c8ff1

doc/source/main.py

@@ -34,8 +34,11 @@ class Checks(upgradecheck.UpgradeCommands):
 
 
 def main():
-    inst = Checks()
+    return upgradecheck.main(
-    return upgradecheck.main(cfg.CONF, inst.check)
+        conf=cfg.CONF,
+        project='myprojectname',
+        upgrade_command=Checks(),
+    )
 
 
 if __name__ == '__main__':

doc/source/usage.rst

@@ -48,3 +48,10 @@ function.
 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.
+
+Example
+-------
+
+The following is a fully functional example of implementing a check command:
+
+.. literalinclude:: main.py

oslo_upgradecheck/tests/test_upgradecheck.py

@@ -19,6 +19,10 @@ test_upgradecheck
 Tests for `upgradecheck` module.
 """
 
+import os.path
+import subprocess
+import sys
+
 import mock
 from oslo_config import cfg
 from oslotest import base
@@ -92,3 +96,14 @@ class TestMain(base.BaseTestCase):
     def test_main_success(self):
         inst = SuccessCommands()
         self._run_test(inst, 0)
+
+
+class TestExampleFile(base.BaseTestCase):
+    def test_example_main(self):
+        path = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                            '../../doc/source/main.py')
+        # The example includes both a passing and failing test, which means the
+        # overall result is failure.
+        self.assertEqual(
+            upgradecheck.Code.FAILURE,
+            subprocess.call([sys.executable, path, 'upgrade', 'check']))