[trafficserver] branch master updated: Adding doc/README.md (#8420)

[bn...@apache.org]

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

bneradt 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 4bdfb7d  Adding doc/README.md (#8420)
4bdfb7d is described below

commit 4bdfb7d74304817dd528b7f4d22116d9d5b874da
Author: Brian Neradt <br...@gmail.com>
AuthorDate: Thu Oct 14 12:17:58 2021 -0500

    Adding doc/README.md (#8420)
    
    This adds a README describing and providing an example of how to build
    the docs.
    
    Fixes #8410
---
 doc/README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..b4bd40d
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,55 @@
+# Apache Traffic Server Documentation
+
+This directory contains the source code for Traffic Server documentation.
+
+# Build
+
+## Package Requirements
+Traffic Server documentation is built using the Sphinx documentation generator.
+The Sphinx build tool is distributed as a Python package. A Pipfile is provided
+to conveniently configure a Python virtual environment with the needed Sphinx
+packages.
+
+In addition to the Sphinx Python package requirements, building the
+documentation will also require Java and graphviz system packages to be
+installed.
+
+## Build Steps
+By default, building the Traffic Server documentation is not configured via the
+Automake configure script. It is enabled using the `--enable-docs`
+configuration switch.
+
+Here is an example shell session that can be used to build the HTML version of
+the Traffic Server documentation:
+
+```bash
+cd doc
+
+# Create the Python virtual environment with Sphinx and other documentation
+# dependencies installed.
+pipenv install
+
+# Enter the Python virtual environment.
+pipenv shell
+
+# Configure and build an HTML version of the documentation.
+cd ../
+autoreconf -fi
+./configure --enable-docs
+cd doc
+make -j $(nproc) html
+```
+
+Once the build completes, you can use Python's
+[http.server](https://docs.python.org/3/library/http.server.html) module to
+create a local test HTTP server to view the built documentation. **Note:**
+http.server is only designed for test purposes, not for production use.
+
+```bash
+cd docbuild/html
+python3 -m http.server 8888
+Serving HTTP on 0.0.0.0 port 8888 (http://0.0.0.0:8888/) ...
+```
+
+You can then view the rendered HTML using your browser of choice and navigating
+to the `http://0.0.0.0:8888/` URL.