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>
This commit is contained in:
Akihiro Motoki 2017-07-12 23:43:49 +00:00 committed by Stephen Finucane
parent a9719bc23e
commit 3e028aa340
4 changed files with 50 additions and 10 deletions

View File

@ -40,7 +40,9 @@ else:
# ones.
extensions = [
'sphinx.ext.autodoc',
'cliff.sphinxext',
]
if has_openstackdocstheme:
extensions.append('openstackdocstheme')

View File

@ -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

View File

@ -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/

View File

@ -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