mirror of
https://github.com/github/codeql.git
synced 2025-12-18 01:33:15 +01:00
89 lines
3.5 KiB
ReStructuredText
89 lines
3.5 KiB
ReStructuredText
QL language documentation
|
||
#########################
|
||
|
||
Overview
|
||
********
|
||
|
||
The QL language documentation is written in reStructuredText and converted to
|
||
HTML for manual publication on `help.semmle.com <https://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 <https://www.sphinx-doc.org/en/master/glossary.html#term-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.
|
||
|
||
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>
|
||
|
||
Building and previewing the QL training presentations
|
||
*****************************************************
|
||
|
||
To build the QL training presentations, you need to install a Sphinx extension
|
||
called `hieroglyph <https://github.com/nyergler/hieroglyph>`__.
|
||
|
||
After installing hieroglyph, you can build the QL 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-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 <https://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.
|