# Trino documentation The `docs` module contains the reference documentation for Trino. - [Writing and contributing](#writing-and-contributing) - [Tools](#tools) - [Fast doc build option](#fast-doc-build-option) - [Default build](#default-build) - [Viewing documentation](#viewing-documentation) - [Versioning](#versioning) - [Style check](#style-check) - [Contribution requirements](#contribution-requirements) - [Workflow](#workflow) - [Videos](#videos) - [Docker container](#docker-container) ## Writing and contributing We welcome any contributions to the documentation. Contributions must [follow the same process as code contributions](https://trino.io/development/) 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](https://developers.google.com/style) - [Highlights](https://developers.google.com/style/highlights) - [Word list](https://developers.google.com/style/word-list) - [Style and tone](https://developers.google.com/style/tone) - [Writing for a global audience](https://developers.google.com/style/translation) - [Cross-references](https://developers.google.com/style/cross-references) - [Present tense](https://developers.google.com/style/tense) The Google guidelines include more material than listed here, and are used as a guide that enable easy decision making about proposed doc changes. Changes to existing documentation to follow these guidelines are underway. As a specific style note, because different readers may perceive the phrases "a SQL" or "an SQL" to be incorrect depending on how they pronounce SQL, aim to avoid use of "a/an SQL" in Trino documentation. Try to reword, re-order, or adjust writing so that it is not necessary. If there is absolutely no way around it, default to using "a SQL." Other useful resources: - [Style check](#style-check) - [Google Technical Writing Courses](https://developers.google.com/tech-writing) - [Myst guide](https://mystmd.org/guide) ## Tools Documentation source files can be found in [Myst Markdown](https://mystmd.org/) (`.md`) format in `src/main/sphinx` and sub-folders. Refer to the [Myst guide](https://mystmd.org/guide) and the existing documentation for more information about how to write and format the documentation source. The engine used to create the documentation in HTML format is the Python-based [Sphinx](https://www.sphinx-doc.org). The [fast doc build option](#fast-doc-build-option) requires *only* a local installation of [Docker Desktop on Mac](https://docs.docker.com/docker-for-mac/install/) or [Docker Engine on Linux](https://docs.docker.com/engine/install/). No other tools are required. The default formal build of the docs is performed with Apache Maven, which requires an installation of a Java Development Kit. ## Fast doc build option For fast 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 other than Docker. You can run the Sphinx build on a fresh clone of the project, with no prerequisite commands. For example: ```bash docs/build ``` Sphinx attempts to perform an incremental build, but this does not work in all cases, such as after editing the CSS. You can force a full rebuild by removing the ``target/html`` directory: ```bash rm -rf docs/target/html ``` ## Default build The default build uses Apache Maven and Java as does the rest of the Trino build. You only need to have built the current Trino version from the root. That is, before building the docs the first time, run the following command: ```bash ./mvnw clean install -DskipTests ``` Subsequently, you can build the doc site using the Maven wrapper script: ```bash ./mvnw -pl docs clean install ``` If you have Maven installed and available on the path, you can use the `mvn` command directly. This also performs other checks, and is the authoritative way to build the docs. However, using Maven is also somewhat slower than using Sphinx directly. ## Viewing documentation However you build the docs, the generated HTML files can be found in the folder `docs/target/html/`. You can open the file `docs/target/html/index.html` in a web browser on macOS with ```bash open docs/target/html/index.html ``` or on Linux with ```bash xdg-open docs/target/html/index.html ``` Or you can directly call your browser of choice with the same filename. For example, on Ubuntu with Chromium: ```bash chromium-browser docs/target/html/index.html ``` Alternatively, you can start a web server with that folder as root, such as with the following Python command. You can then open [http://localhost:4000](http://localhost:4000) in a web browser. ```bash cd 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 ``build`` command and refresh the browser. ## Versioning The version displayed in the resulting HTML is read by default from the top level Maven `pom.xml` file `version` field. To deploy a specific documentation set (such as a SNAPSHOT version) as the release version you must override the pom version with the `TRINO_VERSION` environment variable. ```bash TRINO_VERSION=355 docs/build ``` If you work on the docs for more than one invocation, you can export the variable and use it with Sphinx. ```bash export TRINO_VERSION=354 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. ## Style check The project contains a configured setup for [Vale](https://vale.sh) and the Google developer documentation style. Vale is a command-line tool to check for editorial style issues of a document or a set of documents. Install vale with brew on macOS or follow the instructions on the website. ``` brew install vale ``` The `docs` folder contains the necessary configuration to use vale for any document in the repository: * `.vale` directory with Google style setup * `.vale/Vocab/Base/accept.txt` file for additional approved words and spelling * `.vale.ini` configuration file configured for rst and md files With this setup you can validate an individual file from the root by specifying the path: ``` vale src/main/sphinx/overview/use-cases.md ``` You can also use directory paths and all files within. Treat all output from vale as another help towards better docs. Fixing any issues is not required, but can help with learning more about the [Google style guide](https://developers.google.com/style) that we try to follow. ## Contribution requirements To contribute corrections or new explanations to the Trino documentation requires only a willingness to help and submission of your [Contributor License Agreement](https://github.com/trinodb/cla) (CLA). ## Workflow The procedure to add a documentation contribution is the same as for [a code contribution](https://trino.io/development/process.html). * In the Trino project's [GitHub Issues list](https://github.com/trinodb/trino/issues), identify documentation issues by filtering on the [``docs`` label](https://github.com/trinodb/trino/issues?q=is%3Aissue+is%3Aopen+label%3Adocs). * If you want to help Trino documentation, but don't know where to start, look in the Issues list for both the [``docs`` and ``good first issue`` labels](https://github.com/trinodb/trino/issues?q=is%3Aissue+is%3Aopen+label%3Adocs+label%3A%22good+first+issue%22). * If the doc fix you have in mind does not yet have an issue, add one (which requires a signed CLA). Add the ``docs`` label to your new issue. * You can discuss proposed doc changes in the #docs channel of the [Trino Slack](https://trino.io/slack.html). * For a larger contribution, create a GitHub pull request as described in [GitHub documentation](https://docs.github.com/en/github/getting-started-with-github). In brief, this means: * [Create a fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of the [trinodb/trino](https://github.com/trinodb/trino) repository. * Create a working branch in your fork. * Make your edits in your working branch and push them to your fork. * In a browser, open your fork in GitHub, which offers to submit a pull request for you. ## Videos 1. See [**Contributing to the Trino documentation**](https://www.youtube.com/watch?v=yseFM3ZI2ro) for a five-minute video introduction. Note that this video uses the old RST source format. 2. You might select a GitHub doc issue to work on that requires you to verify how Trino handles a situation, such as [adding documentation](https://github.com/trinodb/trino/issues/7660) for SQL functions. In this case, the five-minute video [Learning Trino SQL with Docker](https://www.youtube.com/watch?v=y58sb9bW2mA) gives you a starting point for setting up a test system on your laptop. ## Docker container The build of the docs uses a Docker container that includes Sphinx and the required libraries. The container is referenced in the `SPHINX_IMAGE` variable in the `build` script. The specific details for the container are available in `Dockerfile`, and `requirements.in`. The file `requirements.txt` must be updated after any changes to `requirements.in`. The container must be published to the GitHub container registry at ghcr.io with the necessary access credentials and the following command, after modification of the version tag `xxx` to the new desired value as used in the `build` script: ``` docker buildx build docs --platform=linux/arm64,linux/amd64 --tag ghcr.io/trinodb/build/sphinx:xxx --provenance=false --push ``` Note that the version must be updated and the command automatically also publishes the container with support for arm64 and amd64 processors. This is necessary so the build performs well on both hardware platforms. After the container is published, you can update the `build` script and merge the related pull request. Example PRs: * https://github.com/trinodb/trino/pull/17778 * https://github.com/trinodb/trino/pull/13225