Merge "Generate demoapp CLI refernece"

4 files changed, 50 insertions, 10 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index f58872b..7c72ba7 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 26dc7aa..3002e78 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 fb20308..5c44426 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
+========
+
+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`)
+-------------------------------------------
 
-Take a sample `setup.cfg` file, which is based on the `setup.cfg` for the
-`python-openstackclient` project:
+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 4cdef3c..78d8299 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