Glance-where-are-the-docs

This info is accurate as of 29 April 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.
• status: being reworked in Newton
  • source is being migrated from WADL to Swagger to yaml ; docs will be generated by Sphinx ; code to do this should be available at Newton RC-1
• posted at http://api.openstack.org/api-ref.html
• file bugs at: http://bugs.launchpad.net/openstack-api-site

== API Reference (Narrative style)

• currently in the glance-specs repo
• currently published with the specs

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 at least partially generated from the glance config files, so check with doc team about where to make changes
  • 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.