Jump to: navigation, search

Difference between revisions of "Documentation/Builds"

(Location of documentation (current))
(Source and target locations of documentation (current))
Line 1: Line 1:
  
 
== Source and target locations of documentation (current) ==
 
== Source and target locations of documentation (current) ==
 +
 +
Remember that there are branches of the openstack-manuals and other repositories that indicate where docs are published to in addition to this mapping. For example, from stable/grizzly, doc source files are published to docs.openstack.org/grizzly and from the master branch, doc source files are published to docs.openstack.org/trunk by our lovely Jenkins butlers aways at the ready.
 +
 
=== Installation guides ===
 
=== Installation guides ===
 
{| class="wikitable sortable"
 
{| class="wikitable sortable"

Revision as of 19:57, 21 June 2013

Source and target locations of documentation (current)

Remember that there are branches of the openstack-manuals and other repositories that indicate where docs are published to in addition to this mapping. For example, from stable/grizzly, doc source files are published to docs.openstack.org/grizzly and from the master branch, doc source files are published to docs.openstack.org/trunk by our lovely Jenkins butlers aways at the ready.

Installation guides

Document Source location Target location
Basic Installation Guide for Ubuntu 12.04 (LTS) and Debian Wheezy https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/basic-install http://docs.openstack.org/grizzly/basic-install/apt/content/
Basic Installation Guide for Fedora 18 https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/basic-install http://docs.openstack.org/grizzly/basic-install/yum/content/
Installation Guide for Red Hat Enterprise Linux, CentOS, and Fedora https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-install http://docs.openstack.org/grizzly/openstack-compute/install/yum/content/
Installation Guide for Ubuntu 12.04 (LTS) https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-install http://docs.openstack.org/grizzly/openstack-compute/install/apt/content/

Configuration guides

Document Source location Target location
Block Storage Service Administration Guide https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-block-storage-admin http://docs.openstack.org/grizzly/openstack-block-storage/admin/content/
Compute Administration Guide https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-compute-admin http://docs.openstack.org/grizzly/openstack-compute/admin/content/
Networking Administration Guide https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-network-connectivity-admin http://docs.openstack.org/grizzly/openstack-network/admin/content/
Object Storage Administration Guide https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-object-storage-admin http://docs.openstack.org/grizzly/openstack-object-storage/admin/content/
Operations Guide https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-ops http://docs.openstack.org/trunk/openstack-ops/content/
High Availability Guide https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-ha http://docs.openstack.org/trunk/openstack-ha/content/index.html
Virtual Machine Image Guide https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-image http://docs.openstack.org/trunk/openstack-image/content/

User and developer guides

Document Source location Target location
API Quick Start https://github.com/openstack/api-site/tree/master/api-quick-start http://docs.openstack.org/api/quick-start/content/
Programming OpenStack Compute API with Shell and Python, 1st ed. https://github.com/openstack/api-site/tree/master/openstack-api-programming http://docs.openstack.org/api/openstack-compute/programmer/content/
Clients Guide https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/cli-guide http://docs.openstack.org/cli/quick-start/content/
API Reference https://github.com/openstack/api-site/tree/master/api-ref http://api.openstack.org/api-ref.html
Block Storage Service API v2 Reference https://github.com/openstack/volume-api/tree/master/v2 http://docs.openstack.org/api/openstack-block-storage/2.0/content/
Block Storage Service API v1 Reference https://github.com/openstack/volume-api/tree/master/v1 N/A
Compute API v2 and Extensions Reference https://github.com/openstack/compute-api http://docs.openstack.org/api/openstack-compute/2/content/
Identity Service API v2.0 Reference https://github.com/openstack/identity-api http://docs.openstack.org/api/openstack-identity-service/2.0/content/
Networking API v2.0 Reference https://github.com/openstack/netconn-api http://docs.openstack.org/api/openstack-network/2.0/content/
Image Service API v2 Reference https://github.com/openstack/image-api/tree/master/openstack-image-service-api/src/markdown http://docs.openstack.org/api/openstack-image-service/2.0/content/
Image Service API v1 Reference https://github.com/openstack/image-api/tree/master/openstack-image-service-api/src/docbkx http://docs.openstack.org/api/openstack-image-service/1.1/content/
Object Storage API v1 Reference https://github.com/openstack/object-api http://docs.openstack.org/api/openstack-object-storage/1.0/content/

Contributor guides

Document Source location Target location
Python Developer Documentation https://github.com/openstack/<project>/tree/master/doc/source/, such as https://github.com/openstack/nova/tree/master/doc/source http://docs.openstack.org/developer/openstack-projects.html
Language Bindings and Python Clients https://github.com/openstack/python-<project>client/tree/master/doc/source/, such as https://github.com/openstack/python-novaclient/tree/master/doc/source http://docs.openstack.org/developer/language-bindings.html
OpenStack Project Infrastructure https://github.com/openstack-infra/config/tree/master/doc/source http://ci.openstack.org/
Tempest Testing Project https://github.com/openstack/tempest/tree/master/doc/source http://docs.openstack.org/developer/tempest/

Build jobs and pom.xml

The build jobs live in the github.com/openstack-infra/config repository. The build jobs build the books for the branches listed below.

The book files, including the pom.xml files, live in the following github.com/openstack/ repositories:

  • openstack-manuals, three branches, essex, folsom, master
  • openstack-admin-manual-compute (1) essex, folsom, master
  • openstack-admin-manual-netconn (1) essex, folsom, master
  • openstack-admin-manual-object (1) essex, folsom, master
  • openstack-cli-guide (1) folsom, master
  • openstack-glossary (1) folsom, master
  • openstack-install-deploy-guide-apt-fedora (1, shared with install/deploy ubuntu) essex, folsom, master
  • openstack-install-deploy-guide-ubuntu (shared with above) essex, folsom, master
  • openstack-basic-install (1) folsom, master
  • openstack-ha (1) folsom, master
  • openstack-ops (1) folsom, master
  • api-site (no branches for API docs)
  • openstack-api-programming guide (1)
  • api-quick-start (1)
  • api-reference (1)
  • compute-api (3)
  • image-api (2)
  • object-api (1)
  • netconn-api (2)
  • volume-api (1)
  • identity-api (2)
  • operations-guide (1)

Total: 23 (ops) +14 (api) =37 books build with jobs, 24 pom.xml files get built

Maven Plugin

The Maven Plugin is updated periodically with features we may want to incorporate in the OpenStack build process. Specifically 1.8.0 is what we use for Grizzly documentation as it contains features designed to make life easier. These changes also required some changes in pom.xml for each book. All these changes have been incorporated so this is information to describe the settings in pom.xml. A major new feature of this version of the plugin is that images are automatically handled for you. This saves two steps and adds a level of validation.

You no longer have to add a postProcess section to your pom.xml configuration to copy image files into the webhelp output directory unless you want to do a clean up step of deleting the renamed directory.

Instead, these settings tell the build where to place the built files.

 <targetDirectory>target/docbkx/webhelp/${release.path.name}/openstack-compute</targetDirectory>
 <webhelpDirname>admin</webhelpDirname>
 <pdfFilenameBase>bk-compute-adminguide-${release.path.name}</pdfFilenameBase>

The clouddocs-maven-plugin automatically detects which images you use in your document and copies them to the output directory. When you use .svg graphics, you do not have to create a .png version. Now, when you generate web help, the clouddocs-maven-plugin automatically converts the .svg to a .png file and uses it instead. You want to ensure all images have the <figure> tag and use contentwidth="6in" as an attribute on the <imageobject>. The system also checks for the availability of images before proceeding with the build, but you may still see "Figure not found" errors that you can safely ignore.

When you generate web help, by default the plugin now automatically generates a PDF and puts it in the webhelp directory, so links will no longer break to the PDF. You can also remove any pdf processing instructions from the book file itself.