Merge "Generate demoapp CLI refernece"

This commit is contained in:
Jenkins 2017-10-13 14:42:23 +00:00 committed by Gerrit Code Review
commit 8b298342b7
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