From c5079cbc7a287922d54dded20bc6be1f8ac49528 Mon Sep 17 00:00:00 2001
From: Ben Nemec <bnemec@redhat.com>
Date: Mon, 8 Oct 2018 17:51:14 +0000
Subject: [PATCH] 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
---
 .../__main__.py => doc/source/main.py             |  7 +++++--
 doc/source/usage.rst                              |  7 +++++++
 oslo_upgradecheck/tests/test_upgradecheck.py      | 15 +++++++++++++++
 3 files changed, 27 insertions(+), 2 deletions(-)
 rename oslo_upgradecheck/__main__.py => doc/source/main.py (90%)

diff --git a/oslo_upgradecheck/__main__.py b/doc/source/main.py
similarity index 90%
rename from oslo_upgradecheck/__main__.py
rename to doc/source/main.py
index 5213d0e..984f6c8 100644
--- a/oslo_upgradecheck/__main__.py
+++ b/doc/source/main.py
@@ -34,8 +34,11 @@ class Checks(upgradecheck.UpgradeCommands):
 
 
 def main():
-    inst = Checks()
-    return upgradecheck.main(cfg.CONF, inst.check)
+    return upgradecheck.main(
+        conf=cfg.CONF,
+        project='myprojectname',
+        upgrade_command=Checks(),
+    )
 
 
 if __name__ == '__main__':
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 1ddd87c..e4a5aad 100644
--- a/doc/source/usage.rst
+++ b/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
diff --git a/oslo_upgradecheck/tests/test_upgradecheck.py b/oslo_upgradecheck/tests/test_upgradecheck.py
index fc1d0fe..7b16f1c 100644
--- a/oslo_upgradecheck/tests/test_upgradecheck.py
+++ b/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']))