openstack/openstack-manuals
Code Issues Proposed changes

[Contributor Guide] Content Docs builds to RST

Browse Source 
This patch:
1. Converts the page https://wiki.openstack.org/wiki/Documentation/Builds
   to RST.
2. Fixes small grammar mistakes.
3. Fixes the outdated content ("changing Icehouse/Havana to Juno/Kilo,
   updating the note about status of user guides conversion to RST, etc).
4. Changes the Maven plug-in version from 1.8.0 for Grizzly to 2.1.4
   for Kilo.
5. Changes https://github.com/openstack... links with
   http://git.openstack.org/cgit/openstack ones throughout the doc.

Change-Id: Ie1177aebc7e492de56a7fcaaa881a12ac106aa51
This commit is contained in:
Olena Logvinova 2015-09-21 15:10:12 +03:00
parent cc0f298f6c
commit e96f4df3e0
2 changed files with 308 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

307
doc/contributor-guide/source/docs_builds.rst Normal file
View File

@ -0,0 +1,307 @@
.. _docs_builds:
====================
Documentation builds
====================
Documentation source and target locations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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/kilo release branch, doc source files are
published to docs.openstack.org/kilo, and from the master branch, doc
source files are published to docs.openstack.org/draft 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 only built from the release branches (stable/release_name)
like the example above of stable/kilo.
.. note::
Installation guides are being migrated to RST/Sphinx. See
`Documentation/Migrate`_ for more information.
.. 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/kilo/install-guide/install/zypper/content
* - Installation Guide for Red Hat Enterprise Linux, CentOS, and Fedora
- http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
- http://docs.openstack.org/kilo/install-guide/install/yum/content
* - Installation Guide for Ubuntu 14.04 (LTS)
- http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
- http://docs.openstack.org/kilo/install-guide/install/apt/content
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/content
* - Configuration Reference
- http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/config-reference
- http://docs.openstack.org/kilo/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/high-availability-guide/content
* - 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/content
Guides for end users
--------------------
.. list-table::
:header-rows: 1
* - Document
- Source location
- Target location
* - API Quick Start
- http://git.openstack.org/cgit/openstack/api-site/tree/api-quick-start
- http://docs.openstack.org/api/quick-start/content
* - 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.
.. list-table::
:header-rows: 1
* - 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 :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 build for the currently supported branches
(juno, kilo), development happens on the master branch. The continuously
released books are only build 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/stackforge/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

1
doc/contributor-guide/source/index.rst
View File

@ -19,6 +19,7 @@ Contents
rst-conv.rst rst-conv.rst
docs-structure.rst docs-structure.rst
content-specs.rst content-specs.rst
docs_builds.rst
Search in this guide Search in this guide
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~