Glance-where-are-the-docs

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:
 * 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/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.