Difference between revisions of "Glance-where-are-the-docs"
m (→"operator docs") |
m (→OpenStack Manuals) |
||
(15 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
− | This info is accurate as of | + | This info is accurate as of 23 June 2016. |
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) | 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) | ||
Line 7: | Line 7: | ||
</div> | </div> | ||
− | == "dev docs" written | + | == "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 | * generated from the rst files in the doc/source directory in the source code | ||
+ | ** https://github.com/openstack/glance | ||
* posted at: | * posted at: | ||
− | ** | + | ** http://docs.openstack.org/developer/glance/ |
** http://docs.openstack.org/developer/python-glanceclient/ | ** 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 | * content: should contain information for contributors to the Glance project itself | ||
* file bugs at: | * file bugs at: | ||
** https://bugs.launchpad.net/glance | ** https://bugs.launchpad.net/glance | ||
** https://bugs.launchpad.net/python-glanceclient | ** https://bugs.launchpad.net/python-glanceclient | ||
+ | * 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: | + | * 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. |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
* file bugs at: http://bugs.launchpad.net/openstack-api-site | * file bugs at: http://bugs.launchpad.net/openstack-api-site | ||
+ | * posted at http://api.openstack.org/api-ref.html (right now that URL is a frozen WADL version) | ||
+ | ** currently posted at http://developer.openstack.org/api-ref/image/ | ||
+ | * source code: | ||
+ | ** https://github.com/openstack/glance in api-ref/source directory | ||
+ | ** v1 is merged, v2 is under review | ||
− | == API | + | == API Reference (Narrative style) == |
− | * | + | * currently in the glance-specs repo |
− | * | + | * currently published with the specs |
− | * | + | * posted at: |
− | * | + | ** http://specs.openstack.org/openstack/glance-specs/specs/api/v1/image_service_v1_api.html |
+ | ** http://specs.openstack.org/openstack/glance-specs/specs/api/v2/image-api-v2.html | ||
+ | * source code: | ||
+ | ** https://github.com/openstack/glance-specs in specs/api directory | ||
+ | |||
+ | == Glance installation guide == | ||
+ | * under development, see http://docs.openstack.org/contributor-guide/project-install-guide.html | ||
− | == | + | == OpenStack Manuals == |
− | * | + | * audience: consumers of OpenStack in their various roles. The manuals are broken into Installation, Ops & Admin, and User Guides. |
* file bugs at: https://bugs.launchpad.net/openstack-manuals | * file bugs at: https://bugs.launchpad.net/openstack-manuals | ||
− | * ''OpenStack | + | * source: https://github.com/openstack/openstack-manuals |
+ | * Find more on documentation team processes hereː http://docs.openstack.org/contributor-guide/ | ||
+ | * ''OpenStack Cloud Administrator Guide'' | ||
** content: installation and administration information | ** content: installation and administration information | ||
− | |||
− | |||
− | |||
** source files for glance related stuff | ** source files for glance related stuff | ||
− | *** doc/admin-guide- | + | *** openstack-manuals/doc/admin-guide/source/compute-images-instances.rst |
− | *** doc/cli-reference/ | + | *** (may be some other stuff, and files are occasionally split/reorganized) |
− | *** doc/config-reference/image-service | + | ** posted at: http://docs.openstack.org/admin-guide/ |
− | ** | + | * "OpenStack Command-Line Interface Reference" |
− | ** posted at: http://docs.openstack.org/ | + | ** openstack-manuals/doc/cli-reference/source/glance_property_keys.rst (suggested values for common image properties) |
+ | ** openstack-manuals/doc/cli-reference/source/glance.rst (automatically generated from python-glanceclient help, so make changes in the glanceclient tree, not here) | ||
+ | ** posted at http://docs.openstack.org/cli-reference/ | ||
+ | * "OpenStack Configuration Reference" | ||
+ | ** doc/config-reference/source/image-service | ||
+ | *** these are RST files that provide introductions to sections of the document | ||
+ | *** the content displaying the options is generated from where the options are defined in the Glance code | ||
+ | *** corrections/clarifications to the option descriptions must be corrected in the Glance code | ||
+ | ** posted at: http://docs.openstack.org/mitaka/config-reference/ | ||
* ''OpenStack Virtual Machine Image Guide'' (not glance-specific) | * ''OpenStack Virtual Machine Image Guide'' (not glance-specific) | ||
** content: how to obtain, create, and modify virtual machine images that are compatible with OpenStack | ** content: how to obtain, create, and modify virtual machine images that are compatible with OpenStack | ||
− | ** source: doc/image-guide | + | ** source: openstack-manuals/doc/image-guide/source/ |
− | ** posted at: http://docs.openstack.org/image-guide | + | ** posted at: http://docs.openstack.org/image-guide/ |
− | == End User Guide | + | == End User Guide == |
− | * | + | * source: openstack-manuals/doc/user-guide/source/ |
− | + | ** (not sure what Glance content is in there ATM) | |
− | + | * posted at: http://docs.openstack.org/user-guide/ | |
− | ** | ||
− | * posted at: http://docs.openstack.org/user-guide | ||
* file bugs at: http://bugs.launchpad.net/openstack-manuals | * file bugs at: http://bugs.launchpad.net/openstack-manuals | ||
<div style="margin-top:10ex"> | <div style="margin-top:10ex"> | ||
− | For other projects, see https://wiki.openstack.org/wiki/Documentation | + | * For other projects, see http://docs.openstack.org/contributor-guide/docs-builds.html#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 | + | * Also, join #openstack-doc on Freenode for real time answers to questions. |
</div> | </div> |
Latest revision as of 18:44, 23 June 2016
This info is accurate as of 23 June 2016.
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.
- file bugs at: http://bugs.launchpad.net/openstack-api-site
- posted at http://api.openstack.org/api-ref.html (right now that URL is a frozen WADL version)
- currently posted at http://developer.openstack.org/api-ref/image/
- source code:
- https://github.com/openstack/glance in api-ref/source directory
- v1 is merged, v2 is under review
API Reference (Narrative style)
- currently in the glance-specs repo
- currently published with the specs
- posted at:
- source code:
- https://github.com/openstack/glance-specs in specs/api directory
Glance installation guide
- under development, see http://docs.openstack.org/contributor-guide/project-install-guide.html
OpenStack Manuals
- audience: consumers of OpenStack in their various roles. The manuals are broken into Installation, Ops & Admin, and User Guides.
- file bugs at: https://bugs.launchpad.net/openstack-manuals
- source: https://github.com/openstack/openstack-manuals
- Find more on documentation team processes hereː http://docs.openstack.org/contributor-guide/
- OpenStack Cloud Administrator Guide
- content: installation and administration information
- source files for glance related stuff
- openstack-manuals/doc/admin-guide/source/compute-images-instances.rst
- (may be some other stuff, and files are occasionally split/reorganized)
- posted at: http://docs.openstack.org/admin-guide/
- "OpenStack Command-Line Interface Reference"
- openstack-manuals/doc/cli-reference/source/glance_property_keys.rst (suggested values for common image properties)
- openstack-manuals/doc/cli-reference/source/glance.rst (automatically generated from python-glanceclient help, so make changes in the glanceclient tree, not here)
- posted at http://docs.openstack.org/cli-reference/
- "OpenStack Configuration Reference"
- doc/config-reference/source/image-service
- these are RST files that provide introductions to sections of the document
- the content displaying the options is generated from where the options are defined in the Glance code
- corrections/clarifications to the option descriptions must be corrected in the Glance code
- posted at: http://docs.openstack.org/mitaka/config-reference/
- doc/config-reference/source/image-service
- OpenStack Virtual Machine Image Guide (not glance-specific)
- content: how to obtain, create, and modify virtual machine images that are compatible with OpenStack
- source: openstack-manuals/doc/image-guide/source/
- posted at: http://docs.openstack.org/image-guide/
End User Guide
- source: openstack-manuals/doc/user-guide/source/
- (not sure what Glance content is in there ATM)
- posted at: http://docs.openstack.org/user-guide/
- file bugs at: http://bugs.launchpad.net/openstack-manuals
- For other projects, see http://docs.openstack.org/contributor-guide/docs-builds.html#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.