mirror of
https://github.com/github/codeql.git
synced 2025-12-16 16:53:25 +01:00
114 lines
4.4 KiB
ReStructuredText
114 lines
4.4 KiB
ReStructuredText
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 </CONTRIBUTING.md>`__.
|
|
|
|
Project structure
|
|
*****************
|
|
|
|
The project contains:
|
|
|
|
- an ``index.html`` file, the project's
|
|
`master document <https://www.sphinx-doc.org/en/master/glossary.html#term-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 <https://www.sphinx-doc.org/en/master/man/sphinx-build.html>`__
|
|
from the project's
|
|
`source directory <https://www.sphinx-doc.org/en/master/glossary.html#term-source-directory>`__.
|
|
For example, to generate the HTML output for a project in the
|
|
``<docs-output>`` directory you would use:
|
|
|
|
.. code::
|
|
|
|
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
|
|
<http://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder>`__.
|
|
|
|
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 <https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext>`__.
|
|
|
|
Building and previewing the CodeQL training presentations
|
|
*********************************************************
|
|
|
|
To build the training presentations, you need to install a Sphinx extension
|
|
called `hieroglyph <https://github.com/nyergler/hieroglyph>`__.
|
|
You also need to install `graphviz <https://graphviz.gitlab.io/download/>`__, 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
|
|
|
|
.. code::
|
|
|
|
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 <https://github.com/github/codeql/blob/main/docs/codeql/ql-training/template.rst>`__.
|
|
|
|
Viewing the current version of the CodeQL documentation
|
|
*******************************************************
|
|
|
|
The documentation for the most recent release is
|
|
published to `codeql.github.com <https://codeql.github.com>`__.
|
|
There, you can find the documentation for the CodeQL queries,
|
|
the CodeQL standard libraries, and can learn about CodeQL.
|