Jump to: navigation, search

Documentation/Builds

< Documentation
Revision as of 20:31, 18 February 2015 by Annegentle (talk | contribs) (Installation guides)

Documentation source and target locations

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

Installation guides

These guides are not built to /trunk and are only built from stable/relname branches.

Document Source location Target location
Installation Guide for Debian 7.0 https://github.com/openstack/openstack-manuals/tree/master/doc/install-guide use docs-draft on review.openstack.org for interim reviews
Installation Guide for openSUSE and SUSE Linux Enterprise Server https://github.com/openstack/openstack-manuals/tree/master/doc/install-guide http://docs.openstack.org/juno/install-guide/install/zypper/content/
Installation Guide for Red Hat Enterprise Linux, CentOS, and Fedora https://github.com/openstack/openstack-manuals/tree/master/doc/install-guide http://docs.openstack.org/juno/install-guide/install/yum/content/
Installation Guide for Ubuntu 12.04 (LTS) https://github.com/openstack/openstack-manuals/tree/master/doc/install-guide http://docs.openstack.org/juno/install-guide/install/apt/content/

Guides for deployers and administrators

Document Source location Target location
Architecture Design Guide https://github.com/openstack/openstack-manuals/tree/master/doc/arch-design http://docs.openstack.org/arch-design/content/
Configuration Reference https://github.com/openstack/openstack-manuals/tree/master/doc/config-reference http://docs.openstack.org/trunk/config-reference/content/
Cloud Administrator Guide https://github.com/openstack/openstack-manuals/tree/master/doc/admin-guide-cloud http://docs.openstack.org/admin-guide-cloud/content/
High Availability Guide https://github.com/openstack/ha-guide/tree/master/doc/ha-guide http://docs.openstack.org/high-availability-guide/content/index.html
Operations Guide https://github.com/openstack/operations-guide http://docs.openstack.org/trunk/openstack-ops/content/
Security Guide https://github.com/openstack/security-doc/tree/master/security-guide http://docs.openstack.org/security-guide/content
Virtual Machine Image Guide https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-image http://docs.openstack.org/openstack-image/content/

Guides for end users

Note: The End User Guide and Admin User Guide are being migrated to RST/Sphinx. See Documentation/Migrate for more information.

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/
End User Guide https://github.com/openstack/openstack-manuals/tree/master/doc/user-guide http://docs.openstack.org/user-guide/content/
Admin User Guide https://github.com/openstack/openstack-manuals/tree/master/doc/user-guide-admin http://docs.openstack.org/user-guide-admin/content/
Command Line Interface Reference https://github.com/openstack/openstack-manuals/tree/master/doc/cli-reference http://docs.openstack.org/cli-reference/content/

Developer guides

Document Source location Target location
API Reference https://github.com/openstack/api-site/tree/master/api-ref http://developer.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 http://docs.openstack.org/api/openstack-block-storage/1.0/content
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/

API Complete Reference Pages (HTML)

POM file location: api-site/api-ref/pom.xml

Document Source location Target location
OpenStack API Complete Reference api-site/api-ref/target/docbkx/html http://developer.openstack.org/api-ref.html
Block Storage API v2.0 api-site/api-ref/target/docbkx/html/api-ref-blockstorage.html http://developer.openstack.org/api-ref-blockstorage.html
Compute API v2 extensions api-site/api-ref/target/docbkx/html/api-ref-compute-v2-ext.html http://developer.openstack.org/api-ref-compute-v2.html
Compute API v2 api-site/api-ref/target/docbkx/html/api-ref-compute-v2.html http://developer.openstack.org/api-ref-compute-v2-ext.html
Compute API v3 (EXPERIMENTAL) api-site/api-ref/target/docbkx/html/api-ref-compute-v3.html http://developer.openstack.org/api-ref-compute-v3.html
Identity API v3 api-site/api-ref/target/docbkx/html/api-ref-identity.html http://developer.openstack.org/api-ref-identity.html
Image Service API v2 api-site/api-ref/target/docbkx/html/api-ref-image.html http://developer.openstack.org/api-ref-image.html
Networking API v2.0 api-site/api-ref/target/docbkx/html/api-ref-networking.html http://developer.openstack.org/api-ref-networking.html
Object Storage API v1 api-site/api-ref/target/docbkx/html/api-ref-objectstorage.html http://developer.openstack.org/api-ref-objectstorage.html
Orchestration API v1.0 api-site/api-ref/target/docbkx/html/api-ref-orchestration.html http://developer.openstack.org/api-ref-orchestration.html
Telemetry API v2.0 api-site/api-ref/target/docbkx/html/api-ref-telemetry.html http://developer.openstack.org/api-ref-telemetry.html

API Complete Reference Guides (PDFs)

POM file location: api-site/api-ref-guides/pom.xml

Document Source location Target location
Block Storage API v2.0 api-site/api-ref-guides/target/docbkx/pdf/bk-api-ref-blockstorage.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-blockstorage.pdf
Compute API v2 extensions api-site/api-ref-guides/target/docbkx/pdf/bk-api-ref-compute-v2-ext.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-compute-v2-ext.pdf
Compute API v2 api-site/api-ref-guides/target/docbkx/pdf/bk-api-ref-compute-v2.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-compute-v2.pdf
Compute API v3 (EXPERIMENTAL) api-site/api-ref-guides/target/docbkx/pdf/api-ref-compute-v3.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-compute-v3.pdf
Identity API v3 api-site/api-ref-guides/target/docbkx/pdf/bk-api-ref-identity.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-identity.pdf
Image Service API v2 api-site/api-ref-guides/target/docbkx/pdf/bk-api-ref-image.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-image.pdf
Networking API v2.0 api-site/api-ref-guides/target/docbkx/pdf/bk-api-ref-networking.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-networking.pdf
Object Storage API v1 api-site/api-ref-guides/target/docbkx/pdf/bk-api-ref-objectstorage.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-objectstorage.pdf
Orchestration API v1.0 api-site/api-ref-guides/target/docbkx/pdf/bk-api-ref-orchestration.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-orchestration.pdf
Telemetry API v2.0 api-site/api-ref-guides/target/docbkx/pdf/bk-api-ref-telemetry.pdf http://developer.openstack.org/api-ref-guides/bk-api-ref-telemetry.pdf

Contributor guides

Generally, the docs.openstack.org/developer documentation is meant for contributors to OpenStack projects. Each project's repo has a doc/source directory where RST source files are stored. They are built automatically with Sphinx when the patch is merged. For example, see http://git.openstack.org/cgit/openstack/horizon/tree/doc/source for the horizon contributor documentation source and http://docs.openstack.org/developer/horizon/ for the built documentation.

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

The build jobs for documentation are stored in the github.com/openstack-infra/config repository. The modules/openstack_project/files/zuul/layout.yaml file and the modules/openstack_project/files/jenkins_job_builder/config/manuals-jobs.yaml or api-docs.yaml file contain the Jenkins build jobs that build to the docs.openstack.org and developer.openstack.org sites, copying built files via FTP.

The release specific books are build for the currently supported branches (havana, icehouse), development happens on the master branch. The continously released books are only build on the master branch.

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>${basedir}/target/docbkx/webhelp/admin-guide-cloud<targetDirectory>
 <webhelpDirname>/</webhelpDirname>
 <pdfFilenameBase>bk-admin-guide-cloud-latest</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.

SNAPSHOT builds

To build with the latest SNAPSHOT version of the plugin, do the following:

  1. Clone the clouddocs-maven-plugin: git clone https://git.openstack.org/stackforge/clouddocs-maven-plugin
  2. cd into the repo: cd clouddocs-maven-plugin
  3. Build the plugin: mvn clean install
  4. Edit your document's pom.xml file to depend on the current snapshot version of the plugin. E.g. 1.12.1-SNAPSHOT
  5. Build the document: mvn clean generate-sources

Gates

Like other projects, the documentation projects use a number of gates that do automatic testing of patches.

The current gates are:

  • gate-openstack-manuals-tox-checklinks
  • gate-openstack-manuals-tox-checkniceness
  • gate-openstack-manuals-tox-checksyntax
  • gate-openstack-manuals-tox-checkdeletions
  • gate-openstack-manuals-tox-doc-publish-checkbuild
  • gate-openstack-manuals-tox-checklang

Checklang Gate

We only gate on manual/language combinations that are translated sufficiently. For example, in openstack-manuals this includes Japanese with the Security Guide, HA Guide and Install Guides.

  • If an import from transifex fails, creates a failure, we do not approve the import.
  • If any other patch fails, the failure might get ignored.
  • In any case of failure, a bug gets reported against the localization project (launchpad link)

Markdown and DocBook

When a source file is markdown, the Jenkins jobs converts it to DocBook then builds with the Maven plugin.

The basic script is:

pandoc -f markdown -t docbook -s ${FILEPATH} |  xsltproc -o - /usr/share/xml/docbook/stylesheet/docbook5/db4-upgrade.xsl - |  xmllint  --format - | sed -e "s,<article,<chapter xml:id=\"$FILENAME\"," | sed -e 's,</article>,</chapter>,' > ${DIRPATH}/$FILENAME.xml

Then, run mvn clean generate-sources on the resulting FILENAME.xml file.

Typically the best route would be to create a Jenkins slave since it'll have all the dependencies. However if you don't want to set up your own Jenkins setup, these are the packages that have to be installed on an Ubuntu server that does the doc build:

  • asciidoc
  • xsltproc
  • docbook-xml
  • docbook5-xml
  • docbook-xsl
  • sgml-data