From e0836fa10f559062f6140815121473568bd9eb55 Mon Sep 17 00:00:00 2001
From: Brian Neradt <brian.neradt@gmail.com>
Date: Wed, 13 Oct 2021 23:21:55 +0000
Subject: [PATCH] Adding doc/README.md

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(+)
 create mode 100644 doc/README.md

diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 00000000000..b4bd40d5dbf
--- /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.