Difference between revisions of "Glance-where-are-the-docs"
m |
m |
||
| Line 7: | Line 7: | ||
</div> | </div> | ||
| − | == "dev docs" written | + | == "dev docs" written by the OpenStack developers working on Glance == |
| − | * audience: software developers who want to work on Glance and/or the python-glanceclient | + | * audience: there are two primary audiences: |
| + | *# software developers who want to work on Glance and/or the python-glanceclient | ||
| + | *# Glance users: "Developer docs should be anything you feel is relevant to Glance users that isn't covered in openstack-manuals. Basically, manuals can't cover everything, so this is where you make up the shortfall" (Lara Brindley, current Docs PTL) | ||
* generated from the rst files in the doc/source directory in the source code | * generated from the rst files in the doc/source directory in the source code | ||
** https://github.com/openstack/glance | ** https://github.com/openstack/glance | ||
| Line 23: | Line 25: | ||
** It will create a directory /opt/stack/glance/doc/build which has html and man subdirectories | ** It will create a directory /opt/stack/glance/doc/build which has html and man subdirectories | ||
| − | == | + | == API Reference Documentation == |
| − | * audience: | + | * audience: prospective end users -- the intended audience consists of application developers and SDK developers who need precise and accurate information about the REST APIs implemented by Glance. |
| − | * | + | * status: being reworked in Liberty following this spec: https://review.openstack.org/#/c/177934/ |
| − | * | + | * generated from files in https://github.com/openstack/api-site |
| − | + | * posted at http://api.openstack.org/api-ref.html | |
| − | |||
| − | |||
| − | |||
* file bugs at: http://bugs.launchpad.net/openstack-api-site | * file bugs at: http://bugs.launchpad.net/openstack-api-site | ||
| + | * note: There used to be narrative style API Reference Docs The source code is still at https://github.com/openstack/image-api, but it's been moved to the attic. The repo README has this note: "To update Image API information, please submit patches to http://git.openstack.org/cgit/openstack/glance-specs for a new API feature and to http://git.openstack.org/cgit/openstack/api-site for implemented API information." | ||
| − | == | + | == OpenStack Manuals == |
| − | * | + | * audience: consumers of OpenStack in their various roles. The manuals are broken into Installation, Ops & Admin, and User Guides. |
| − | + | ||
| − | + | == under construction == | |
| − | + | (ignore all below here) | |
| − | |||
* generated from XML files in http://git.openstack.org/cgit/openstack/openstack-manuals | * generated from XML files in http://git.openstack.org/cgit/openstack/openstack-manuals | ||
* file bugs at: https://bugs.launchpad.net/openstack-manuals | * file bugs at: https://bugs.launchpad.net/openstack-manuals | ||
Revision as of 13:04, 30 July 2015
This info is accurate as of 5 September 2014.
Info about contributing to the documentation is here: https://wiki.openstack.org/wiki/Documentation (basically, you clone a repo and use gerrit just like you do for code)
Note to Glance devs: file a bug when you plan to contribute to/update documentation so there's no duplication of effort.
Contents
"dev docs" written by the OpenStack developers working on Glance
- audience: there are two primary audiences:
- software developers who want to work on Glance and/or the python-glanceclient
- Glance users: "Developer docs should be anything you feel is relevant to Glance users that isn't covered in openstack-manuals. Basically, manuals can't cover everything, so this is where you make up the shortfall" (Lara Brindley, current Docs PTL)
- generated from the rst files in the doc/source directory in the source code
- posted at:
- http://docs.openstack.org/developer/glance/
- http://docs.openstack.org/developer/python-glanceclient/
- status: not versioned, should always reflect master
- content: should contain information for contributors to the Glance project itself
- file bugs at:
- generate the docs locally withː
- tox -e docs
- It will create a directory /opt/stack/glance/doc/build which has html and man subdirectories
API Reference Documentation
- audience: prospective end users -- the intended audience consists of application developers and SDK developers who need precise and accurate information about the REST APIs implemented by Glance.
- status: being reworked in Liberty following this spec: https://review.openstack.org/#/c/177934/
- generated from files in https://github.com/openstack/api-site
- posted at http://api.openstack.org/api-ref.html
- file bugs at: http://bugs.launchpad.net/openstack-api-site
- note: There used to be narrative style API Reference Docs The source code is still at https://github.com/openstack/image-api, but it's been moved to the attic. The repo README has this note: "To update Image API information, please submit patches to http://git.openstack.org/cgit/openstack/glance-specs for a new API feature and to http://git.openstack.org/cgit/openstack/api-site for implemented API information."
OpenStack Manuals
- audience: consumers of OpenStack in their various roles. The manuals are broken into Installation, Ops & Admin, and User Guides.
under construction
(ignore all below here)
- generated from XML files in http://git.openstack.org/cgit/openstack/openstack-manuals
- file bugs at: https://bugs.launchpad.net/openstack-manuals
- Find more on documentation team processes hereː https://wiki.openstack.org/wiki/Documentation/HowTo
- OpenStack Cloud Administrator Guide
- content: installation and administration information
- source files for glance related stuff
- doc/admin-guide-cloud/images
- (may be some other stuff, and files are occasionally split/reorganized)
- posted at: http://docs.openstack.org/admin-guide-cloud/content/
- "OpenStack Command-Line Interface Reference"
- doc/cli-reference/ch_cli_glance_property_keys.xml (suggested values for common image properties)
- doc/cli-reference/generated/ch_cli_glance_commands.xml (automatically generated from python-glanceclient help)
- posted at http://docs.openstack.org/cli-reference/content/
- "OpenStack Configuration Reference"
- doc/config-reference/image-service
- doc/common/tables/*glance* (automatically generated from glance config help strings)
- posted at: http://docs.openstack.org/icehouse/config-reference/content/
- OpenStack Virtual Machine Image Guide (not glance-specific)
- content: how to obtain, create, and modify virtual machine images that are compatible with OpenStack
- source: doc/image-guide
- posted at: http://docs.openstack.org/image-guide/content/
End User Guide
- also generated from XML files in https://github.com/openstack/openstack-manuals
- source files for glance-specific stuff:
- doc/common/section_cli_glance_manage_images.xml
- doc/common/section_sdk_glance_manage_images.xml
- doc/common/section_getstart_image.xml (I can't figure out where this content is posted)
- source files for glance-specific stuff:
- posted at: http://docs.openstack.org/user-guide/content/
- file bugs at: http://bugs.launchpad.net/openstack-manuals
- For other projects, see https://wiki.openstack.org/wiki/Documentation/Builds#Documentation_source_and_target_locations
- For general documentation project info, see https://wiki.openstack.org/wiki/Documentation
- Also, join #openstack-doc on Freenode for real time answers to questions.
