QL language documentation

Overview

The QL language documentation is written in reStructuredText and converted to HTML for manual publication on help.semmle.com using Sphinx.

For more information on writing in reStructuredText, see http://docutils.sourceforge.net/rst.html.

For more information on Sphinx, see https://www.sphinx-doc.org.

Project structure

The QL language documentation currently consists of the following Sphinx projects:

• learn-ql–help topics to help you learn the QL language and write queries
• ql-handbook–a user-friendly guide to the QL language
• ql-spec–formal descriptions of the QL language and QLDoc comments
• support–the languages and frameworks currently supported in QL analysis
• training–QL for variant analysis training material
• ql-training-rst–QL for variant analysis slide shows

Each project contains:

• an index.html file, the project's master document.
• a conf.py file that defines some project-specific configuration values
• one or more reStructuredText source files

Shared configuration values are specified in global-conf.py, which is found in the global-sphinx-files directory. This directory also contains any other files, such as templates and stylesheets, that are used by multiple projects. Images used in the QL documentation are located in the images directory.

The ql-training-rst project contains the source files, themes, and static files used to generate the QL training presentations. It uses a different configuration from the other projects, and is built using an extension specifically designed for HTML slide shows. For more information, see Building and previewing the QL training presentations below.

Building and previewing the QL language documentation

To build and preview the QL documentation locally, you need to install Sphinx. For installation options, see https://github.com/sphinx-doc/sphinx.

Using sphinx-build

After installing Sphinx, you can build the HTML files for a project by running sphinx-build from the project's source directory. For example, to generate the HTML output for a project in the <docs-output> directory you would use:

sphinx-build -b html . <docs-output>

Add the -W flag to turn warnings into errors during the build process. You can use errors reported during the build to debug problems in your source code, such as broken internal links and malformed tables.

Add the -a flag to regenerate all output files. By default, only files that have changed are rebuilt.

Using the reStructuredText Extension for Visual Studio Code

Visual Studio Code has an extension that can be used to preview Sphinx-generated output alongside .rst source code in your IDE. For more information, see the Visual Studio Marketplace.

Building and previewing the QL training presentations

To build the QL training presentations, you need to install a Sphinx extension called hieroglyph.

After installing hieroglyph, you can build the QL training presentations by running sphinx-build, specifying the slides builder. For example

sphinx-build -b slides . <slides-output>

generates html slide shows in the <slides-output> directory when run from the ql-training-rst source directory.

Viewing the current version of the QL language documentation

The QL language documentation for the most recent Semmle release is published to help.semmle.com. There, you can also find the documentation for QL for Eclipse, QL for Visual Studio, QL command-line tools, and LGTM Enterprise.