d4d965f9c6
Explain which guides are continously published and which are versioned, explain the concepts as well. Use liberty instead of kilo as example. Change-Id: I3f3b76bc5f3e663ae88df650d762a11c2227201c
12 KiB
Documentation builds
Documentation source and target locations
Most documents are continously published, they are published only from the master branch and there is no specific version for a stable release, instead they document the releases that the OpenStack community currently maintains. There are also version dependent documents.
In addition to this page, the release and master branches of the openstack-manuals and other repositories indicate where docs are published. For example, from the stable/liberty release branch, doc source files are published to docs.openstack.org/liberty, and from the master branch, doc source files are published for versioned documents to docs.openstack.org/draft and for continously published documents to docs.openstack.org/ by our lovely Jenkins butlers always at the ready.
Some content is completely generated using openstack-doc-tools, such as the configuration option tables and the CLI reference information. You will see this warning in the source file: <!-- This file is automatically generated, do not edit -->.
Refer to the OpenStack Doc Tools for more information on the collection of documentation tools used for content, such as the auto-generation of config tables or CLI references.
Installation guides
These guides are versioned and only built from the release branches (stable/release_name) like the example above of stable/liberty.
| Document | Source location | Target location |
|---|---|---|
| Installation Guide for Debian 8.0 | http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide | use docs-draft on review.openstack.org for interim reviews |
| Installation Guide for openSUSE and SUSE Linux Enterprise Server | http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide | http://docs.openstack.org/liberty/install-guide-obs |
| Installation Guide for Red Hat Enterprise Linux and CentOS | http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide | http://docs.openstack.org/liberty/install-guide-rdo |
| Installation Guide for Ubuntu 14.04 (LTS) | http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide | http://docs.openstack.org/liberty/install-guide-ubuntu |
Guides for deployers and administrators
Note
The Configuration Reference and the Networking Guide are versioned, all other guides are continously published.
Guides for end users
| Document | Source location | Target location |
|---|---|---|
| API Guide | http://git.openstack.org/cgit/openstack/api-site/tree/api-quick-start | http://developer.openstack.org/api-guide/quick-start/ |
| End User Guide | http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/user-guide | http://docs.openstack.org/user-guide |
| Admin User Guide | http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/user-guide-admin | http://docs.openstack.org/user-guide-admin |
| Command Line Interface Reference | http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/cli-reference | http://docs.openstack.org/cli-reference/content |
Developer guides
Each project maintains its own developer guide. We do not publish these on the docs site. See http://docs.openstack.org/developer/openstack-projects.html.
API Complete Reference pages (HTML)
POM file location: api-site/api-ref/pom.xml
Source file location:
- api-site/api-ref/src/docbkx for DocBook files
- api-site/api-ref/src/wadls/<project-name> for WADL files and code samples
Target file location: http://developer.openstack.org/api-ref.html. See the navigation bar on the left side for links to all API reference pages.
API Complete Reference guides (PDFs)
POM file location: api-site/api-ref-guides/pom.xml
Source file location:
- api-site/api-ref-guides/src for DocBook files for books
- api-site/api-ref/src/docbkx for DocBook files for chapters
- api-site/api-ref/src/wadls/<project-name> for WADL files and code samples
Target file location: http://developer.openstack.org/api-ref-guides/bk-api-ref.pdf. See the navigation bar on the left side for links to all API reference pages. On each reference page, a link for the PDF appears in the upper right corner.
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 | http://git.openstack.org/cgit/openstack/<project>/tree/master/doc/source/, such as http://git.openstack.org/cgit/openstack/nova/tree/doc/source | http://docs.openstack.org/developer/openstack-projects.html |
| Language Bindings and Python Clients | http://git.openstack.org/cgit/openstack/python-<project>client/tree/master/doc/source/, such as http://git.openstack.org/cgit/openstack/python-novaclient/tree/doc/source | http://docs.openstack.org/developer/language-bindings.html |
| OpenStack Project Infrastructure | http://git.openstack.org/cgit/openstack-infra/system-config/tree/doc/source | http://docs.openstack.org/infra/system-config/ |
| Tempest Testing Project | http://git.openstack.org/cgit/openstack/tempest/tree/doc/source | http://docs.openstack.org/developer/tempest/ |
Build jobs
The build jobs for documentation are stored in the http://git.openstack.org/cgit/openstack-infra/project-config
repository. The zuul/layout.yaml file and the jenkins/jobs/manual-jobs.yaml or jenkins/jobs/api-jobs.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 built for the currently supported branches (current and previous releases), development happens on the master branch. The continuously released books are only built on the master branch.
Maven plug-in
The Maven plug-in is updated periodically with features we may want to incorporate in the OpenStack build process. Specifically, 2.1.4 is what we use for Kilo 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 information is to describe the settings in pom.xml. A major new feature of this version of the plug-in 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 plug-in now automatically generates a PDF and puts it in the webhelp directory, so links will no longer break in 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 plug-in, do the following:
Clone the clouddocs-maven-plugin:
git clone https://git.openstack.org/openstack/clouddocs-maven-pluginOpen the repository:
cd clouddocs-maven-pluginBuild the plug-in:
mvn clean installEdit your document's pom.xml file to depend on the current snapshot version of the plugin. For example, 1.12.1-SNAPSHOT.
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 Zanata fails, 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 i18n project (launchpad link).
If you want to manually run this check on your local workstation you
can use the checklang environment (tox -e checklang). To use this environment, you
first have to install the xml2po utility on your local
workstation. xml2po is part of the gnome-doc-utils and can be installed
with yum install gnome-doc-utils (on RedHat-based
distributions), or zypper install xml2po (on SUSE-based
distributions).