.. 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` switch for enabling documentation builds is ``--enable-docs``. Additional packages required for building the documentation. System installs These should be installed via `yum `__ or `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 `__. 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 `__ 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 `__ 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.