[trafficserver] branch master updated: Doc: Update documentation building documentation.

[am...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

amc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/master by this push:
     new b2705d6  Doc: Update documentation building documentation.
b2705d6 is described below

commit b2705d6a79097058938a13d959eaf66dd32cd33f
Author: Alan M. Carroll <am...@apache.org>
AuthorDate: Wed Feb 21 15:43:37 2018 -0600

    Doc: Update documentation building documentation.
---
 doc/developer-guide/documentation/building.en.rst | 54 +++++++++++++++++++----
 1 file changed, 46 insertions(+), 8 deletions(-)

diff --git a/doc/developer-guide/documentation/building.en.rst b/doc/developer-guide/documentation/building.en.rst
index 220762c..0e98329 100644
--- a/doc/developer-guide/documentation/building.en.rst
+++ b/doc/developer-guide/documentation/building.en.rst
@@ -22,26 +22,64 @@
 Building the Documentation
 **************************
 
-All documentation and related files are located in the source tree under the
-``doc/`` directory. Makefiles are generated automatically by the main configure
-script. The current configure script switch for enabling documentation builds is
-``--enable-docs``. Also make sure you have run ``pip install sphinx`` at some point.
+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
+      Internation support, which is needed if a non-English version is built. Currently a Japanese
+      (``JA``) version is available.
 
 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, it is advisable to clean out the built and intermediate
-files each time by running the following instead (again, from within the ``doc/``
+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 && make html
+    make clean && make html
 
 This will ensure that make doesn't inadvertantly 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.
-

-- 
To stop receiving notification emails like this one, please contact
amc@apache.org.