The presto-docs module contains the reference documentation for Presto.

• Writing and contributing
• Tools
• Default Build
• Faster Build for Authoring
• Viewing Documentation
• Using sphinx-autobuild
• Versioning
• Known Issues

We welcome any contributions to the documentation. Contributions need to follow the same process as code contributions and can be part of your code contributions or separate documentation improvements.

The documentation follows the Google developer documentation style guide for any new documentation:

• Google developer documentation style guide
• Highlights
• Word list
• Style and tone
• Writing for a global audience
• Cross-references
• Present tense

The guidelines include much more material and are used as a guide and enable easy decision making. Existing documentation upgrades to follow the guidelines are ongoing.

Other useful resources:

• Google Technical Writing Courses
• RST cheatsheet

The default build of the docs is performed with Apache Maven.

Documentation source files can be found in Restructured Text (.rst) format in src/main/sphinx and sub-folders.

The engine used to create the documentation in HTML format is the Python-based Sphinx.

The default build is using Apache Maven and Java like for the rest of the Presto build. You just need to have built the current version from the root. Subsequently, you can build the site using the Maven wrapper script.

./mvnw -pl presto-docs clean install

If you have Maven installed and available on the path, you can use mvn directly.

This also performs other checks, and it is the authoritative way to build the docs, however it is somewhat also slower than using Sphinx directly.

For faster local build times when writing documentation, you can run the Sphinx build directly. The build runs inside a Docker container and thus does not require having anything installed locally (except for Docker):

presto-docs/build

Sphinx will attempt to perform an incremental build, but it does not work in all cases, such as after editing the CSS. You can force a full rebuild by doing a Maven clean first:

./mvnw -pl presto-docs clean

However you built the docs, the output HTML files can be found in the folder presto-docs/target/html/.

You can open the file presto-docs/target/html/index.html in a web browser on macOS with

open presto-docs/target/html/index.html

or on Linux with

xdg-open presto-docs/target/html/index.html

Or you can directly call your browser of choice with the filename e.g on Ubuntu with Chromium:

chromium-browser presto-docs/target/html/index.html

Alternatively, you can start a web server with that folder as root, e.g. again with Python and then open https://localhost:4000 in a web browser.

cd presto-docs/target/html/
python3 -m http.server 4000

In order to see any changes from the source files in the HTML output, simply re-run the make command and refresh the browser.

The version displayed in the resulting HTML is read from the top level Maven pom.xml file version field, by default.

To deploy a specific documentation set (e.g. a SNAPSHOT version) as release version you have to override the pom version with the PRESTO_VERSION environment variable.

PRESTO_VERSION=327 presto-docs/build

If you work on the docs for more than one invocation, you can export the variable and use it with sphinx.

export PRESTO_VERSION=327
presto-docs/build

This is especially useful when deploying doc patches for a release where the Maven pom has already moved to the next SNAPSHOT version.