doc/developer-guide/documentation/building.en.rst

.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.

.. include:: ../../common.defs

.. _developer-doc-building:

Building the Documentation
**************************

All documentation and related files are located in the source tree under the :ts:git:`doc`
directory. The Makefiles must be generated by the main configure script. The current :ref:`configure
script<admin-configuration-options>` switch for enabling documentation builds is ``--enable-docs``.

Additional packages required for building the documentation.

System installs
   These should be installed via `yum <https://fedoraproject.org/wiki/Yum>`__ or
   `dnf <https://fedoraproject.org/wiki/DNF>`__.

   graphviz
      Graph visualization, used for diagrams in many places.

   java
      A java based utility is run to generate diagrams and so a java executor is required.

   python2-pip
      PIP for installing Python packages. Install this if you are using Python 2.

   python3-pip
      PIP for installing Python packages. Install this if you are using Python 3.

PIP installs
   These should be installed using `pip <https://pypi.python.org/pypi/pip>`__.

   sphinx
      A Python package that is the based Sphinx Documentation.

   sphinx-rtd-theme
      Style package for the preferred ATS documentation style.

   sphinxcontrib-plantuml
      Support for using `plantuml <http://plantuml.com/PlantUML_Language_Reference_Guide.pdf>`__ inline.

   sphinx-intl
      International support, which is needed if a non-English version is built. Currently a Japanese
      (``JA``) version is available.

   These should be also installed using `pipenv
   <https://docs.pipenv.org/>`__ and :ts:git:`doc/Pipfile`. To setup the environment, run below commands from within the :ts:git:`doc/` directory of the |TS| source tree::

      pipenv install
      pipenv shell


With a configured source tree, building the documentation requires only the
invocation ``make html`` from within ``doc/``. For repeated builds while working
on the documentation doing ``make html`` again is sufficient. After fixing all warnings / errors,
however, it is advisable to clean out the built and intermediate
files by running the following instead (again, from within the ``doc/``
directory of the |TS| source tree)::

    make clean && make html

This will ensure that make doesn't inadvertently skip the regeneration of any
targets.

.. note::

   It is expected that any PR updating the documentation builds without any errors *or warnings*.
   This can be easy to miss if the full build is not done before submitting the pull request.

To view the built documentation, you may point any browser to the directory
``doc/docbuild/html/``. If you are building the documentation on your local
machine, you may access the HTML documentation files directly without the need
for a full-fledged web server, as all necessary resources (CSS, Javascript, and
images) are referenced using relative paths and there are no server-side scripts
necessary to render the documentation.