Jump to: navigation, search

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

m (→‎OpenStack Manuals)
 
(38 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
This info is accurate as of 27 June 2013.
+
This info is accurate as of 23 June 2016.
  
−
== "dev docs" written by developers working on glance ==
+
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)
 +
 
 +
<div style="background-color: yellow">
 +
Note to Glance devs: file a bug when you plan to contribute to/update documentation so there's no duplication of effort.
 +
</div>
 +
 
 +
== "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/glance/
 
** http://docs.openstack.org/developer/python-glanceclient/
 
** http://docs.openstack.org/developer/python-glanceclient/
−
== "API docs" written by Top Professionals ==
+
** status: not versioned, should always reflect master
−
* generated from files in https://github.com/openstack/image-api
+
* content: should contain information for contributors to the Glance project itself
−
* v1 generated from XML files in openstack-image-service-api/src/docbkx
+
* file bugs at:
−
** posted at: http://docs.openstack.org/api/openstack-image-service/1.1/content/
+
** https://bugs.launchpad.net/glance
−
* v2 generated from markdown files in openstack-image-service-api/src/markdown
+
** https://bugs.launchpad.net/python-glanceclient
−
** posted at: http://docs.openstack.org/api/openstack-image-service/2.0/content/
+
* generate the docs locally withː
−
== "operator docs" ==
+
** tox -e docs
−
*  generated from XML files in https://github.com/openstack/openstack-manuals
+
** It will create a directory /opt/stack/glance/doc/build which has html and man subdirectories
−
* for glance:
+
 
−
**  doc/src/docbkx/common/adding-images.xml
+
== API Reference Documentation ==
−
** doc/src/docbkx/common/ch_image_mgmt.xml
+
* 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.
−
**  doc/src/docbkx/common/image-formats.xml
+
* file bugs at: http://bugs.launchpad.net/openstack-api-site
−
**  (may be some other stuff, and files are occasionally split/reorganized)
+
* posted at http://api.openstack.org/api-ref.html (right now that URL is a frozen WADL version)
−
* posted at: http://docs.openstack.org/grizzly/openstack-compute/admin/content/
+
** currently posted at http://developer.openstack.org/api-ref/image/
−
== "quickstart" guide ==
+
* source code:
−
* generated from XML files in https://github.com/openstack/openstack-manuals
+
** https://github.com/openstack/glance in api-ref/source directory
−
** doc/src/docbkx/cli-guide/src/glance_cli_commands.xml
+
** v1 is merged, v2 is under review
−
** doc/src/docbkx/cli-guide/src/glance_cli_howto.xml
+
 
−
* posted at: http://docs.openstack.org/cli/quick-start/content/
+
== 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
 +
 
 +
<div style="margin-top:10ex">
 +
* 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.
 +
</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.

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

API Reference Documentation

API Reference (Narrative style)

Glance installation guide

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

Retrieved from "https://wiki.openstack.org/w/index.php?title=Glance-where-are-the-docs&oldid=127237"