From 1d30fb78f115c194f9e428089495f7842acd90ef Mon Sep 17 00:00:00 2001 From: Marilyn Beck Date: Wed, 9 Jun 2021 13:41:20 -0700 Subject: [PATCH] Add instructions to README.md for building Presto docs --- README.md | 4 ++++ presto-docs/README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 presto-docs/README.md diff --git a/README.md b/README.md index f15ea87366cbd..b8fb6d590ce2a 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,10 @@ We recommend you use IntelliJ as your IDE. The code style template for the proje * Use an assertion from Airlift's `Assertions` class if there is one that covers your case rather than writing the assertion by hand. Over time we may move over to more fluent assertions like AssertJ. * When writing a Git commit message, follow these [guidelines](https://chris.beams.io/posts/git-commit/). +## Building the Documentation + +To learn how to build the docs, see the [docs README](presto-docs/README.md). + ## Building the Web UI The Presto Web UI is composed of several React components and is written in JSX and ES6. This source code is compiled and packaged into browser-compatible Javascript, which is then checked in to the Presto source code (in the `dist` folder). You must have [Node.js](https://nodejs.org/en/download/) and [Yarn](https://yarnpkg.com/en/) installed to execute these commands. To update this folder after making changes, simply run: diff --git a/presto-docs/README.md b/presto-docs/README.md new file mode 100644 index 0000000000000..47f0f07961409 --- /dev/null +++ b/presto-docs/README.md @@ -0,0 +1,40 @@ +# Building the documentation + +Presto documentation is authored in `rst` format and published using [Sphinx](https://www.sphinx-doc.org). The rst files are located in `presto-docs/src/main/sphinx` and sub-folders. + +## Prerequisites + +Building the presto-docs module requires Python3 with virtual environment. You can check if you have it installed by running: +``` +python3 -m venv --help +``` + +To install venv: +``` +python3 -m pip install --user virtualenv +``` + +## Building manually +The default build uses Apache Maven to download dependencies and generate the HTML. You can run it as follows: +``` +cd presto-docs +mvn install +``` +Or, to build the documentation more quickly: +``` +cd presto-docs +./build +``` +## Viewing the documentation +When the build is complete, you'll find the output HTML files in the `target/html/` folder. + +To view the docs, you can open the file `target/html/index.html` in a web browser on macOS with +``` +open target/html/index.html +``` +Or, you can start a web server e.g., using Python: +``` +cd target/html/ +python3 -m http.server +``` +and open [http://localhost:8000](http://localhost:8000) in a web browser.