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

Revision as of 23:44, 23 January 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)

"dev docs" written for Python developers by developers working on glance

• 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/
• 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 subdir’s

"API docs" written for application developers and people who upload images programmatically

• 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
• generated from files in http://git.openstack.org/cgit/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

API Quick Reference Docs

• generated from XML files in: http://git.openstack.org/cgit/openstack/api-site
• posted at: http://api.openstack.org/api-ref.html
• content: quick ref docs and WADLs for the API
• file bugs at: http://bugs.launchpad.net/openstack-api-site

"operator docs"

• 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)
• posted at: http://docs.openstack.org/user-guide/content/
• file bugs at: http://bugs.launchpad.net/openstack-manuals