324 lines
12 KiB
ReStructuredText
324 lines
12 KiB
ReStructuredText
.. _docs_builds:
|
|
|
|
====================
|
|
Documentation builds
|
|
====================
|
|
|
|
Documentation source and target locations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Most documents are continuously 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 continuously 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.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - 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
|
|
---------------------------------------
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Document
|
|
- Source location
|
|
- Target location
|
|
|
|
* - Architecture Design Guide
|
|
- http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/arch-design
|
|
- http://docs.openstack.org/arch-design/
|
|
|
|
* - Configuration Reference
|
|
- http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/config-reference
|
|
- http://docs.openstack.org/liberty/config-reference/content
|
|
|
|
* - Cloud Administrator Guide
|
|
- http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/admin-guide-cloud
|
|
- http://docs.openstack.org/admin-guide-cloud
|
|
|
|
* - High Availability Guide
|
|
- http://git.openstack.org/cgit/openstack/ha-guide
|
|
- http://docs.openstack.org/ha-guide
|
|
|
|
* - Networking Guide
|
|
- http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/networking-guide
|
|
- http://docs.openstack.org/liberty/networking-guide
|
|
|
|
* - Operations Guide
|
|
- http://git.openstack.org/cgit/openstack/operations-guide/
|
|
- http://docs.openstack.org/openstack-ops/content
|
|
|
|
* - Security Guide
|
|
- http://git.openstack.org/cgit/openstack/security-doc/tree/security-guide
|
|
- http://docs.openstack.org/security-guide
|
|
|
|
* - Virtual Machine Image Guide
|
|
- http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/image-guide
|
|
- http://docs.openstack.org/image-guide/
|
|
|
|
.. note::
|
|
The Configuration Reference and the Networking Guide are versioned,
|
|
all other guides are continuously published.
|
|
|
|
Guides for end users
|
|
--------------------
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - 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
|
|
|
|
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.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Document
|
|
- Source location
|
|
- Target location
|
|
|
|
* - Documentation Contributor Guide
|
|
- http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/contributor-guide
|
|
- http://docs.openstack.org/contributor-guide/
|
|
|
|
* - 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 :file:`zuul/layout.yaml` file and the
|
|
:file:`jenkins/jobs/manual-jobs.yaml` or :file:`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.
|
|
|
|
.. _mvn:
|
|
|
|
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/glossary<targetDirectory>
|
|
<webhelpDirname>/</webhelpDirname>
|
|
<pdfFilenameBase>bk-glossary</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-plugin
|
|
|
|
#. Open the repository::
|
|
|
|
cd clouddocs-maven-plugin
|
|
|
|
#. Build the plug-in::
|
|
|
|
mvn clean install
|
|
|
|
#. Edit 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 (:command:`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
|
|
:command:`yum install gnome-doc-utils` (on RedHat-based distributions), or
|
|
:command:`zypper install xml2po` (on SUSE-based distributions).
|
|
|
|
.. Links:
|
|
.. _`release`: https://wiki.openstack.org/wiki/Releases
|
|
.. _`OpenStack Doc Tools`: http://git.openstack.org/cgit/openstack/openstack-doc-tools/
|
|
.. _`auto-generation of config tables`: http://git.openstack.org/cgit/openstack/openstack-doc-tools/tree/autogenerate_config_docs/README.rst
|
|
.. _`Documentation/Migrate`: https://wiki.openstack.org/wiki/Documentation/Migrate#Installation_Guide_Migration
|
|
.. _`launchpad link`: https://bugs.launchpad.net/openstack-i18n
|