Jump to: navigation, search

Difference between revisions of "Documentation/Builds"

(Developer guides)
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
Read the new content in the [http://docs.openstack.org/contributor-guide/docs-builds.html Documentation Contributor Guide].
 +
 
{{OpenStack_Documentation_Navbar}}
 
{{OpenStack_Documentation_Navbar}}
 
== Documentation source and target locations ==
 
 
In addition to this page, the [[https://wiki.openstack.org/wiki/Releases release]] and master branches of the openstack-manuals and other repositories indicate where docs are published. For example, from the stable/icehouse release branch, 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.
 
 
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:
 
<nowiki>
 
<!-- This file is automatically generated, do not edit --></nowiki>
 
 
Refer to: [https://github.com/openstack/openstack-doc-tools OpenStack Doc Tools] for more information on the collection of documentation tools used for content such as the [https://github.com/openstack/openstack-doc-tools/blob/master/autogenerate_config_docs/README.rst auto-generation of config tables] or CLI references. 
 
 
=== Installation guides ===
 
 
These guides are only built from the release branches (stable/releasename) like the example above of stable/icehouse.
 
 
{| class="wikitable sortable"
 
|-
 
! 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/kilo/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/kilo/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/kilo/install-guide/install/apt/content/
 
|-
 
|}
 
 
=== Guides for deployers and administrators ===
 
{| class="wikitable sortable"
 
|-
 
! 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/image-guide ||  http://docs.openstack.org/image-guide/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.
 
 
{| class="wikitable sortable"
 
|-
 
! 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/
 
|-
 
|}
 
 
=== API references ===
 
{| class="wikitable sortable"
 
|-
 
! Document !! Source location !! Target location
 
|-
 
| OpenStack API Complete Reference || https://github.com/openstack/api-site/tree/master/api-ref || http://developer.openstack.org/api-ref.html
 
|-
 
| Block Storage API v2 (CURRENT) || https://github.com/openstack/volume-api/tree/master/v2 || http://developer.openstack.org/api-ref-blockstorage-v2.html
 
|-
 
| Block Storage API v1 (SUPPORTED) || https://github.com/openstack/volume-api/tree/master/v1 || http://developer.openstack.org/api-ref-blockstorage-v1.html
 
|-
 
| Compute API v2.1 (CURRENT) || https://github.com/openstack/compute-api || http://developer.openstack.org/api-ref-compute-v2.1.html
 
|-
 
| Compute API v2 (SUPPORTED) || https://github.com/openstack/compute-api || http://developer.openstack.org/api-ref-compute-v2.html
 
|-
 
| Compute API v2 extensions (SUPPORTED) || https://github.com/openstack/compute-api || http://developer.openstack.org/api-ref-compute-v2-ext.html
 
|-
 
| Data Processing API v1.1 (CURRENT) || https://github.com/openstack/dataprocessing-api || http://developer.openstack.org/api-ref-data-processing-v1.1.html
 
|-
 
| 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
 
 
{| class="wikitable sortable"
 
|-
 
! 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
 
 
{| class="wikitable sortable"
 
|-
 
! 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.
 
 
{| class="wikitable sortable"
 
|-
 
! 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:
 
 
# Clone the clouddocs-maven-plugin: git clone https://git.openstack.org/stackforge/clouddocs-maven-plugin
 
# cd into the repo: cd clouddocs-maven-plugin
 
# Build the plugin: mvn clean install
 
# Edit your document's pom.xml file to depend on the current snapshot version of the plugin. E.g. 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 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 ([https://bugs.launchpad.net/openstack-i18n launchpad link])
 
 
If you want to manually run this check on your local workstation you can use the checklang environment (<code>tox -e checklang</code>). 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 <code>yum install gnome-doc-utils</code> (on RedHat-based distributions), or <code>zypper install xml2po</code> (on SUSE-based distributions).
 
 
== 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 <code>mvn clean generate-sources</code> on the resulting <code>FILENAME.xml</code> 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:
 
 
* <code>asciidoc</code>
 
* <code>xsltproc</code>
 
* <code>docbook-xml</code>
 
* <code>docbook5-xml</code>
 
* <code>docbook-xsl</code>
 
* <code>sgml-data</code>
 
  
 
----
 
----
 
[[Category:Documentation]]
 
[[Category:Documentation]]

Latest revision as of 19:20, 26 October 2015

Read the new content in the Documentation Contributor Guide.