Jump to: navigation, search

Difference between revisions of "Blueprint-os-cli-docs"

(Created page with "* '''Launchpad Entry''': [https://blueprints.launchpad.net/openstack-manuals/+spec/blueprint-os-cli-docs| Design for OpenStack Command-line Interface (CLI) Docs] * '''Created...")
 
(→‎Automation of OpenStack CLI Documentation)
 
(8 intermediate revisions by the same user not shown)
Line 2: Line 2:
 
* '''Created''': Diane Fleming
 
* '''Created''': Diane Fleming
 
* '''Contributors''':  
 
* '''Contributors''':  
 +
== 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 commands. Currently, this documentation resides here and is produced manually, though it's cut and paste 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:
+
The automated documentation would appear in the following books (and possibly in other books):
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! Document !! Purpose
+
! Document !! Command Ref
 
|-
 
|-
−
| OpenStack End User Guide || Introduces end users to cloud concepts, common tasks, and ways of interacting with the cloud. <br />
+
| OpenStack End User Guide || http://docs.openstack.org/user-guide/content/nova_summary.html <br />
−
 
 
−
Through examples, shows users how to perform tasks in an OpenStack cloud through:
 
−
 
 
−
* the Horizon dashboard
 
−
* the OpenStack command-line clients
 
−
 
 
−
In an appendix (or appendices), provides reference information that enables users to perform tasks through OpenStack command-line client commands.
 
  
 
|-
 
|-
−
| OpenStack Admin User Guide || Introduces admin users to administrative tasks, and ways of interacting with the cloud. <br />
+
| OpenStack Admin User Guide || http://docs.openstack.org/user-guide-admin/content/nova_summary.html <br />
−
 
 
−
Through examples, shows admin users how to perform administrative tasks in an OpenStack cloud through:
 
−
 
 
−
* the Horizon dashboard
 
−
* the OpenStack command-line clients
 
  
 
|}
 
|}
  
−
'''Content will be shared between the two user guides.'''
+
'''Content is shared between the two user guides.'''
  
−
== Blueprint - CLI documentation automation ==
+
=== 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 41: 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, and so on, and the output for each command, such as nova help boot.<br /><br />
+
* Include both the output from nova help (and other clients), and the output for each command, such as nova help boot.<br /><br />
 +
 
 +
'''Source  repositories''':
 +
 
 +
* [http://git.openstack.org/cgit/openstack/python-ceilometerclient/ openstack/python-ceilometerclient]
 +
* [http://git.openstack.org/cgit/openstack/python-cinderclient/ openstack/python-cinderclient]
 +
* [http://git.openstack.org/cgit/openstack/python-glanceclient/ openstack/python-glanceclient]
 +
* [http://git.openstack.org/cgit/openstack/python-heatclient/ openstack/python-heatclient]
 +
* [http://git.openstack.org/cgit/openstack/python-keystoneclient/ openstack/python-keystoneclient]
 +
* [http://git.openstack.org/cgit/openstack/python-neutronclient/ openstack/python-neutronclient]
 +
* [http://git.openstack.org/cgit/openstack/python-novaclient/ openstack/python-novaclient]
 +
* [http://git.openstack.org/cgit/openstack/python-swiftclient/ openstack/python-swiftclient]
  
−
'''Source  material''':
+
=== Issues/Questions ===
  
−
* [https://www.suse.com/documentation/suse_cloud10/book_cloud_user/?page=/documentation/suse_cloud10/book_cloud_user/data/book_cloud_user.html Suse End User Guide]
+
* What event/s would trigger a regeneration of the docs?  
−
* [http://training.rackspace.com/certification/rackspace-certified-technician-for-openstack/1/ Rackspace-sponsored OpenStack training]
+
* Where would the code reside that auto-generates the CLI docs? In openstack-infra? in openstack/openstack-manuals?
−
* [http://www.openstack.org/software/start/ OpenStack API Quick Start]
 
−
* [http://docs.openstack.org/developer/openstack-projects.html Python Developer Documentation]
 
−
* [http://docs.openstack.org/developer/language-bindings.html Language Bindings Documentation]
 
−
* [http://docs.openstack.org/cli/quick-start/content/index.html OpenStack Clients Guide]
 
−
* [http://docs.openstack.org/run/ OpenStack Administration Guides]
 
−
* [http://docs.openstack.org/api/api-specs.html OpenStack API Specifications]
 
−
* [http://docs.openstack.org/api/openstack-compute/programmer/content/ Programming OpenStack Compute API with Shell and Python]
 

Latest revision as of 14:18, 29 October 2013

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:

Issues/Questions

  • What event/s would trigger a regeneration of the docs?
  • Where would the code reside that auto-generates the CLI docs? In openstack-infra? in openstack/openstack-manuals?
Retrieved from "https://wiki.openstack.org/w/index.php?title=Blueprint-os-cli-docs&oldid=34328"