From 3eb5a4de5e2f5fc6be8c48e3ed730548ff4eece6 Mon Sep 17 00:00:00 2001 From: Olena Logvinova Date: Tue, 13 Oct 2015 19:19:33 +0300 Subject: [PATCH] [Contributor Guide] Build locally section to RST This patch: - translates the below wiki pages to RST: https://wiki.openstack.org/wiki/Documentation/HowTo#Building_Output_Locally https://wiki.openstack.org/wiki/Documentation/HowTo#Using_Tox_to_check_builds - reworks the content (removing outdated info). Change-Id: Ieb0e09c8c98529b6f7413a49100d4c52150ef3dd Implements: blueprint docs-contributor-guide --- .../source/build-locally.rst | 187 ++++++++++++++++++ doc/contributor-guide/source/docs_builds.rst | 8 +- doc/contributor-guide/source/index.rst | 1 + 3 files changed, 193 insertions(+), 3 deletions(-) create mode 100644 doc/contributor-guide/source/build-locally.rst diff --git a/doc/contributor-guide/source/build-locally.rst b/doc/contributor-guide/source/build-locally.rst new file mode 100644 index 0000000000..aa2d53e4cd --- /dev/null +++ b/doc/contributor-guide/source/build-locally.rst @@ -0,0 +1,187 @@ +.. _build_locally: + +Building output locally +~~~~~~~~~~~~~~~~~~~~~~~ + +The openstack-manuals project uses a `tox.ini`_ file with specific sections +that run jobs using the `Tox`_ tool, a virtualenv-based automation of test +activities. + +Tox prerequisites and installation +---------------------------------- + +**Install the prerequisites for Tox:** + +* On Ubuntu or Debian: + + .. code-block:: console + + # apt-get install gcc gettext python-dev libxml2-dev libxslt1-dev \ + zlib1g-dev + + You may need to use :command:`pip install` for some packages. + +* On RHEL or CentOS including Fedora: + + .. code-block:: console + + # yum install gcc python-devel libxml2-devel libxslt-devel + +* On openSUSE or SUSE Linux Enterprise: + + .. code-block:: console + + # zypper install gcc python-devel libxml2-devel libxslt-devel + +**Install python-tox:** + +.. code-block:: console + + # pip install tox + +Build workflow +-------------- + +Once Tox is installed and configured, execute :command:`tox -e ` to +run a particular job: + +* To build all docs (DocBook and RST), open your local openstack-manuals + project and run: + + .. code-block:: console + + tox -e checkbuild + +* To build RST docs, run: + + .. code-block:: console + + tox -e docs + +* To build a specific guide, add the guide folder name to the + :command:`tox -e build` command. For example: + + .. code-block:: console + + tox -e build -- contributor-guide + + + .. note:: This command does not work for the install-guide, as it + contains conditional content. To build specific parts of the + Installation guide, use the commands below: + + .. code-block:: console + + tox -e install-guide-obs + tox -e install-guide-ubuntu + tox -e install-guide-debian + tox -e install-guide-rdo + +This runs the :command:`sphinx-build` command. When the build is finished, +it will be displayed in the ``openstack-manuals/publish-docs`` directory. +You can open the ``.html`` file in a browser to view the resulting output. + +If you do not want to use Tox, install the below prerequisites locally: + +.. code-block:: console + + # pip install sphinx + # pip install openstackdocstheme + +To get the ``.html`` output locally, switch to the directory containing a +``conf.py`` and run: + +.. code-block:: console + + sphinx-build /path/to/source/ path/to/build/ + +The RST source is built into HTML using Sphinx, so that it is displayed on +the *docs.openstack.org/*, for example, +http://docs.openstack.org/user-guide-admin. + +The DocBook source is built into HTML (webhelp) and PDF using XSLT transforms +included to the DocBook project. + +You can find tips how to troubleshoot the build at: +`Documentation/Troubleshooting`_. + +**Build DocBook locally without a Python environment** + +`Maven`_ plug-in must be installed to build the documentation. Run one of the +below commands to install Maven: + +* On Ubuntu or Debian: + + .. code-block:: console + + apt-get install maven + +* On Fedora: + + .. code-block:: console + + yum install maven + +* On openSUSE: + + .. code-block:: console + + zypper install maven + +To build a specific DocBook guide, look for a ``pom.xml`` file within a +subdirectory, switch to that directory, then run the :command:`mvn` command +using Maven plug-in in that directory. For example: + +.. code-block:: console + + cd openstack-manuals/doc/image-guide + mvn clean generate-sources + +Find the generated documentation in the +``openstack-manuals/doc//target`` directory of the guide that you +build. For example: + +* PDF: ``openstack-manuals/doc/image-guide/target/docbkx/webhelp/ + image-guide/image-guide.pdf`` +* HTML: ``openstack-manuals/doc/image-guide/target/docbkx/webhelp/ + image-guide/content/index.html``. + +Using Tox to check builds +------------------------- + +As a part of the review process, Jenkins runs gating scripts to check that +the patch is fine. Locally, you can use the Tox tool to ensure that a patch +works. To check all books, run the following command from the base directory +of repository: + +.. code-block:: console + + tox + +The following individual checks are also availableː + +* :command:`tox -e checkniceness` - to run the niceness tests (for example, + to see extra whitespaces) +* :command:`tox -e checksyntax` - to run syntax checks +* :command:`tox -e checkdeletions` - to check that no deleted files are + referenced +* :command:`tox -e checklinks` - to check whether all the links work +* :command:`tox -e checklang` - to check all the translated manuals +* :command:`tox -e docs` - to build only RST-sourced manuals +* :command:`tox -e checkbuild` - to build all the manuals. This will also + generate a directory ``publish-docs`` that contains the built files for + inspection. + +.. note:: + + * The scripts are not written for Windows, but we encourage + cross-platform work on our scripts. + * If Tox stops working, try :command:`tox --recreate` to rebuild the + environment. + +.. _`Nova developer site`: http://docs.openstack.org/developer/nova/ +.. _`Glance developer site`: http://docs.openstack.org/developer/glance/ +.. _`Documentation/Troubleshooting`: https://wiki.openstack.org/wiki/Documentation/Troubleshooting +.. _`tox.ini`: http://git.openstack.org/cgit/openstack/openstack-manuals/tree/tox.ini +.. _`Tox`: https://tox.readthedocs.org/en/latest/ +.. _`Maven`: http://maven.apache.org/ diff --git a/doc/contributor-guide/source/docs_builds.rst b/doc/contributor-guide/source/docs_builds.rst index 8914715469..a57702d2d5 100644 --- a/doc/contributor-guide/source/docs_builds.rst +++ b/doc/contributor-guide/source/docs_builds.rst @@ -200,9 +200,11 @@ repository. The :file:`zuul/layout.yaml` file and the 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, liberty), development happens on the master branch. The -continuously released books are only build on the master branch. +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 ~~~~~~~~~~~~~ diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index 7a9562afef..d2ed891088 100644 --- a/doc/contributor-guide/source/index.rst +++ b/doc/contributor-guide/source/index.rst @@ -21,6 +21,7 @@ Contents docs-structure.rst content-specs.rst docs_builds.rst + build-locally.rst writing-style.rst json_conventions.rst doc-bugs.rst