Difference between revisions of "Glance-where-are-the-docs"

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.

"dev docs" written by the OpenStack developers working on Glance

audience: there are two primary audiences:
1. software developers who want to work on Glance and/or the python-glanceclient
2. 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
- https://github.com/openstack/glance
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:
- https://bugs.launchpad.net/glance
- 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: 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:
- 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
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/
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.

@@ Line 1: / Line 1: @@
-This info is accurate as of 10 September 2013.
+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)
@@ Line 7: / Line 7: @@
 </div>
-== "dev docs" written for Python developers by developers working on glance ==
+== "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
+** https://github.com/openstack/glance
 * posted at:
-**  http://docs.openstack.org/developer/glance/
+** 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:
 ** https://bugs.launchpad.net/glance
 ** 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 docs" written for application developers and people who upload images programmatically ==
+== API Reference Documentation ==
-* audience: these are "prospective end user docs" that a cloud provider would use as the basis to create custom API docs for their particular cloud
+* 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.
-* generated from files in https://github.com/openstack/image-api
-* v1 generated from XML files in openstack-image-service-api/src/docbkx
-** posted at: http://docs.openstack.org/api/openstack-image-service/1.1/content/
-* v2 generated from markdown files in openstack-image-service-api/src/markdown
-** posted at: http://docs.openstack.org/api/openstack-image-service/2.0/content/
-* content: the API specifications
 * 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 Quick Reference Docs ==
+== API Reference (Narrative style) ==
-* generated from XML files in: https://github.com/openstack/api-site
+* currently in the glance-specs repo
-* posted at: http://api.openstack.org/api-ref.html
+* currently published with the specs
-* content: quick ref docs and WADLs for the API
+* posted at:
-* file bugs at: http://bugs.launchpad.net/openstack-api-site
+** 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
-== "operator docs" ==
+== OpenStack Manuals ==
-*  generated from XML files in https://github.com/openstack/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
-* ''OpenStack Compute Administration Guide''
+* 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-specific stuff:
+** source files for glance related stuff
-*** doc/common/section_glance_cli_manage_images.xml
+***  openstack-manuals/doc/admin-guide/source/compute-images-instances.rst
-*** doc/common/section_glance_image-formats.xml
+***  (may be some other stuff, and files are occasionally split/reorganized)
-** source files for glance related stuff (some suggested values for image properties):
+** posted at: http://docs.openstack.org/admin-guide/
-*** doc/admin-guide-cloud/section_adding-images.xml
+* "OpenStack Command-Line Interface Reference"
-**  (may be some other stuff, and files are occasionally split/reorganized)
+**  openstack-manuals/doc/cli-reference/source/glance_property_keys.rst (suggested values for common image properties)
-** posted at: http://docs.openstack.org/trunk/openstack-compute/admin/content/
+**  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)
 ** content: how to obtain, create, and modify virtual machine images that are compatible with OpenStack
-** source: https://github.com/openstack/openstack-manuals/tree/master/doc/image-guide
+** source: openstack-manuals/doc/image-guide/source/
-** posted at: http://docs.openstack.org/trunk/openstack-image/content/
+** posted at: http://docs.openstack.org/image-guide/
+== End User Guide ==
-== End User Guide (formerly, the "quickstart" guide) ==
+* source: openstack-manuals/doc/user-guide/source/
-* I believe this does not exist any more ... need to check
+** (not sure what Glance content is in there ATM)
-* generated from XML files in https://github.com/openstack/openstack-manuals
+* posted at: http://docs.openstack.org/user-guide/
-** doc/user-guide/section_glance_cli.xml
-** doc/user-guide/section_glance_cli_commands.xml
-* posted at: http://docs.openstack.org/user-guide/content/
 * file bugs at: http://bugs.launchpad.net/openstack-manuals
 <div style="margin-top:10ex">
-For other projects, see https://wiki.openstack.org/wiki/Documentation/Builds#Source_and_target_locations_of_documentation_.28current.29
+* 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.  The documentation team also has "office hours" Mondays at noon EST.
+* Also, join #openstack-doc on Freenode for real time answers to questions.
 </div>