From 3e028aa3402ae6009f256233876d4488ab91688c Mon Sep 17 00:00:00 2001
From: Akihiro Motoki <amotoki@gmail.com>
Date: Wed, 12 Jul 2017 23:43:49 +0000
Subject: [PATCH] Generate demoapp CLI refernece

We have no way to check the cliff sphinxext work expectedly now.
It would be useful if we can check the cliff sphinxext in our doc.

Change-Id: If0578460dd678ffd33c20cf3707c08fa637eaf87
Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>
---
 doc/source/conf.py            |  2 ++
 doc/source/user/demoapp.rst   | 23 ++++++++++++++++++++++-
 doc/source/user/sphinxext.rst | 29 ++++++++++++++++++++++-------
 tox.ini                       |  6 ++++--
 4 files changed, 50 insertions(+), 10 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index f58872b4..7c72ba79 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -40,7 +40,9 @@ else:
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'cliff.sphinxext',
 ]
+
 if has_openstackdocstheme:
     extensions.append('openstackdocstheme')
 
diff --git a/doc/source/user/demoapp.rst b/doc/source/user/demoapp.rst
index 26dc7aa9..3002e783 100644
--- a/doc/source/user/demoapp.rst
+++ b/doc/source/user/demoapp.rst
@@ -61,7 +61,6 @@ The ``simple`` command prints this output to the console:
   sending greeting
   hi!
 
-
 To see help for an individual command, use the ``help`` command::
 
   (.venv)$ cliffdemo help files
@@ -70,6 +69,9 @@ or the ``--help`` option::
 
   (.venv)$ cliffdemo files --help
 
+For more information, refer to the autogenerated documentation :ref:`below
+<demoapp-sphinx>`.
+
 The Source
 ==========
 
@@ -301,3 +303,22 @@ single ``--added-by-hook`` option.
 .. seealso::
 
    :class:`cliff.hooks.CommandHook` -- The API for command hooks.
+
+.. _demoapp-sphinx:
+
+Autogenerated Documentation
+===========================
+
+The following documentation is generated using the following directive, which
+is provided by :doc:`the cliff Sphinx extension <sphinxext>`.
+
+.. code-block:: rest
+
+   .. autoprogram-cliff:: cliff.demo
+      :application: cliffdemo
+
+Output
+------
+
+.. autoprogram-cliff:: cliff.demo
+   :application: cliffdemo
diff --git a/doc/source/user/sphinxext.rst b/doc/source/user/sphinxext.rst
index fb20308d..5c44426d 100644
--- a/doc/source/user/sphinxext.rst
+++ b/doc/source/user/sphinxext.rst
@@ -1,6 +1,9 @@
-==================
-Sphinx Integration
-==================
+====================
+ Sphinx Integration
+====================
+
+Usage
+=====
 
 cliff supports integration with Sphinx by way of a `Sphinx directives`__.
 
@@ -100,11 +103,22 @@ Before using the :rst:dir:`autoprogram-cliff` directive you must add
 
 .. _example:
 
-Example
-=======
+Examples
+========
 
-Take a sample `setup.cfg` file, which is based on the `setup.cfg` for the
-`python-openstackclient` project:
+Simple Example (`demoapp`)
+--------------------------
+
+`cliff` provides a sample application, :doc:`demoapp`, to demonstrate some of the
+features of `cliff`. This application :ref:`is documented <demoapp-sphinx>`
+using the `cliff.sphinxext` Sphinx extension.
+
+Advanced Example (`python-openstackclient`)
+-------------------------------------------
+
+It is also possible to document larger applications, such as
+`python-openstackclient`__. Take a sample `setup.cfg` file, which is a minimal
+version of the `setup.cfg` provided by the `python-openstackclient` project:
 
 .. code-block:: ini
 
@@ -149,3 +163,4 @@ usage examples show the full command name:
 
 __ http://www.sphinx-doc.org/en/stable/extdev/markupapi.html
 __ https://docs.python.org/3/library/fnmatch.html
+__ https://docs.openstack.org/python-openstackclient/
diff --git a/tox.ini b/tox.ini
index 4cdef3c7..78d82994 100644
--- a/tox.ini
+++ b/tox.ini
@@ -17,8 +17,10 @@ install_command = {toxinidir}/tools/tox_install.sh {env:UPPER_CONSTRAINTS_FILE:h
 commands =
   python setup.py test --coverage --coverage-package-name=cliff --slowest --testr-args='{posargs}'
   coverage report --show-missing
-deps = -r{toxinidir}/test-requirements.txt
-    .[docs]
+deps =
+  -r{toxinidir}/test-requirements.txt
+  cliffdemo
+  .[docs]
 
 [testenv:pep8]
 deps = flake8