CodeQL documentation

Overview

The CodeQL documentation in this repository is written in reStructuredText and converted to HTML using Sphinx.

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

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

For information on contributing to CodeQL documentation, see the contributing guide.

Project structure

The project contains:

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

The documentation consists of the following categories:

CodeQL overview
Writing CodeQL queries
CodeQL language guides
QL language reference
CodeQL CLI
CodeQL for Visual Studio Code

The ql-training project contains the source files, themes, and static files used to generate the CodeQL training and variant analysis 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 CodeQL training presentations below.

Building and previewing the CodeQL documentation

To build and preview the documentation and training presentations locally, you need to install Sphinx 1.7.9 using Python 2 (for example: pip install sphinx==1.7.9). More recent versions of Sphinx do not work with hieroglyph, the Sphinx extension that we use to generate HTML slides, as explained below. 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. You can also check external links using Sphinx's external link builder.

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 CodeQL training presentations

To build the training presentations, you need to install a Sphinx extension called hieroglyph. You also need to install graphviz, which is used to generate graphs on some slides.

After installing hieroglyph and graphviz, you can build the 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 source directory.

For more information about creating slides for QL training and variant analysis examples, see the template slide deck.

Viewing the current version of the CodeQL documentation

The documentation for the most recent release is published to codeql.github.com. There, you can find the documentation for the CodeQL queries, the CodeQL standard libraries, and can learn about CodeQL.