Documentation/Builds
Contents
Documentation source and target locations (current)
In addition to this mapping, branches of the openstack-manuals and other repositories indicate where docs are published. 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 always at the ready.
Installation guides
Document | Source location | Target location |
---|---|---|
Installation Guide for Debian 7.0 | https://github.com/openstack/openstack-manuals/tree/master/doc/install-guide | http://docs.openstack.org/trunk/install-guide/install/apt-debian/content/ |
Installation Guide for openSUSE and SUSE Linux Enterprise Server | https://github.com/openstack/openstack-manuals/tree/master/doc/install-guide | http://docs.openstack.org/trunk/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/trunk/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/trunk/install-guide/install/apt/content/ |
Configuration guides
Guides for using the OpenStack dashboard and command-line clients
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
API Reference and Reference Guides
Document | Source location | Target location | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Block Storage API v2.0 | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-blockstorage.pdf | http://api.openstack.org/api-ref-blockstorage.html | |||||||||||||||
Compute API v2 extensions | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-compute-v2-ext.pdf | http://api.openstack.org/api-ref-compute-v2.html | |||||||||||||||
Compute API v2 | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-compute-v2.pdf | http://api.openstack.org/api-ref-compute-v2-ext.html | |||||||||||||||
Compute API v3 (EXPERIMENTAL) | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-compute-v3.pdf | http://api.openstack.org/api-ref-compute-v3.html | |||||||||||||||
Block Storage Service API v2 Reference | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-identity.pdf | http://api.openstack.org/api-ref-identity.html | |||||||||||||||
Block Storage Service API v2 Reference | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-image.pdf | http://api.openstack.org/api-ref-image.html | |||||||||||||||
Block Storage Service API v2 Reference | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-networking.pdf | http://api.openstack.org/api-ref-networking.html | |||||||||||||||
Block Storage Service API v2 Reference | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-objectstorage.pdf http://api.openstack.org/api-ref-objectstorage.html | ||||||||||||||||
Block Storage Service API v2 Reference | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-orchestration.pdf | http://api.openstack.org/api-ref-orchestration.html | |||||||||||||||
Block Storage Service API v2 Reference | api-site/api-ref-guides/target/docbkx/webhelp/api-ref-guides/api-ref-telemetry.pdf | http://api.openstack.org/api-ref-telemetry.html
Contributor guides
Build jobs and pom.xmlThe 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.yaml, 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 api.openstack.org sites, copying built files via FTP. An example patch is here: https://review.openstack.org/#/c/36102/3 for adding a completely new document build. 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:
API docs
Maven PluginThe 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 buildsTo build with the latest SNAPSHOT version of the plugin, do the following:
Markdown and DocBookWhen 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 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:
|