Difference between revisions of "Blueprint-os-cli-docs"
(→Automation of OpenStack CLI Documentation) |
|||
Line 2: | Line 2: | ||
* '''Created''': Diane Fleming | * '''Created''': Diane Fleming | ||
* '''Contributors''': | * '''Contributors''': | ||
− | = Automation of OpenStack CLI Documentation = | + | == Automation of OpenStack CLI Documentation == |
− | == Summary == | + | === Summary === |
This blueprint describes a plan to automate the reference documentation for the OpenStack command-line interfaces (CLI), such as nova, neutron, keystone, swift, and other CLIs. Currently, this documentation resides [http://docs.openstack.org/user-guide/content/nova_summary.html here] and is produced manually by cutting and pasting from the command help output. | This blueprint describes a plan to automate the reference documentation for the OpenStack command-line interfaces (CLI), such as nova, neutron, keystone, swift, and other CLIs. Currently, this documentation resides [http://docs.openstack.org/user-guide/content/nova_summary.html here] and is produced manually by cutting and pasting from the command help output. | ||
Line 9: | Line 9: | ||
Instead, this same documentation will be "scraped" from the source python code by using a tool such as the sphinxcontrib-programoutput plug-in (https://review.openstack.org/#/c/46325/). | Instead, this same documentation will be "scraped" from the source python code by using a tool such as the sphinxcontrib-programoutput plug-in (https://review.openstack.org/#/c/46325/). | ||
− | The automated documentation would appear in the following books: | + | The automated documentation would appear in the following books, and possibly in other books: |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
Line 23: | Line 23: | ||
'''Content is shared between the two user guides.''' | '''Content is shared between the two user guides.''' | ||
− | == Blueprint - CLI documentation | + | === Blueprint - Automation of OpenStack CLI documentation === |
'''Audience''': End users of OpenStack clouds who perform tasks through the OpenStack command-line clients. Also, developers who create applications on top of OpenStack by using the OpenStack APIs. | '''Audience''': End users of OpenStack clouds who perform tasks through the OpenStack command-line clients. Also, developers who create applications on top of OpenStack by using the OpenStack APIs. | ||
<br /> | <br /> | ||
Line 31: | Line 31: | ||
'''Purpose''': | '''Purpose''': | ||
− | * Automate CLI reference documentation from code. | + | * Automate CLI reference documentation by using a plug-in to "scrape" this information from code. |
− | * Include both the output from nova help | + | * Include both the output from nova help (and other clients), and the output for each command, such as nova help boot.<br /><br /> |
− | '''Source | + | '''Source repositories''': |
− | * | + | * http://git.openstack.org/cgit/openstack/ceilometer/ |
− | * | + | * http://git.openstack.org/cgit/openstack/cinder/ |
− | * | + | * http://git.openstack.org/cgit/openstack/glance/ |
− | * | + | * http://git.openstack.org/cgit/openstack/heat/ |
− | * | + | * http://git.openstack.org/cgit/openstack/horizon/ ? |
− | * | + | * http://git.openstack.org/cgit/openstack/keystone/ |
− | * | + | * http://git.openstack.org/cgit/openstack/neutron/ |
− | + | * http://git.openstack.org/cgit/openstack/nova/ | |
− | * | + | * |
Revision as of 14:08, 29 October 2013
- Launchpad Entry: Design for OpenStack Command-line Interface (CLI) Docs
- Created: Diane Fleming
- Contributors:
Automation of OpenStack CLI Documentation
Summary
This blueprint describes a plan to automate the reference documentation for the OpenStack command-line interfaces (CLI), such as nova, neutron, keystone, swift, and other CLIs. Currently, this documentation resides here and is produced manually by cutting and pasting from the command help output.
Instead, this same documentation will be "scraped" from the source python code by using a tool such as the sphinxcontrib-programoutput plug-in (https://review.openstack.org/#/c/46325/).
The automated documentation would appear in the following books, and possibly in other books:
Document | Command Ref |
---|---|
OpenStack End User Guide | http://docs.openstack.org/user-guide/content/nova_summary.html |
OpenStack Admin User Guide | http://docs.openstack.org/user-guide-admin/content/nova_summary.html |
Content is shared between the two user guides.
Blueprint - Automation of OpenStack CLI documentation
Audience: End users of OpenStack clouds who perform tasks through the OpenStack command-line clients. Also, developers who create applications on top of OpenStack by using the OpenStack APIs.
Product info: Icehouse, 2014.1
Purpose:
- Automate CLI reference documentation by using a plug-in to "scrape" this information from code.
- Include both the output from nova help (and other clients), and the output for each command, such as nova help boot.
Source repositories:
- http://git.openstack.org/cgit/openstack/ceilometer/
- http://git.openstack.org/cgit/openstack/cinder/
- http://git.openstack.org/cgit/openstack/glance/
- http://git.openstack.org/cgit/openstack/heat/
- http://git.openstack.org/cgit/openstack/horizon/ ?
- http://git.openstack.org/cgit/openstack/keystone/
- http://git.openstack.org/cgit/openstack/neutron/
- http://git.openstack.org/cgit/openstack/nova/