Docs: Update readme in docs folder

This commit is contained in:
shati-patel 2019-11-15 16:26:43 +00:00 коммит произвёл Shati Patel
Родитель 74ca0e428d
Коммит 08c91b05ac
1 изменённых файлов: 23 добавлений и 23 удалений

Просмотреть файл

@ -1,10 +1,10 @@
QL language documentation
#########################
CodeQL documentation
####################
Overview
********
The QL language documentation is written in reStructuredText and converted to
The CodeQL documentation in this repository 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,
@ -15,13 +15,13 @@ For more information on Sphinx, see https://www.sphinx-doc.org.
Project structure
*****************
The QL language documentation currently consists of the following Sphinx projects:
The 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
- ``learn-ql``–help topics to help you learn CodeQL and write queries
- ``ql-handbook``–a user-friendly guide to the QL language, which underlies CodeQL analysis
- ``ql-spec``–formal descriptions of the QL language and QLDoc comments
- ``support``–the languages and frameworks currently supported in QL analysis
- ``ql-training``–source files for the QL training and variant analysis examples slide decks
- ``support``–the languages and frameworks currently supported in CodeQL analysis
- ``ql-training``–source files for the CodeQL training and variant analysis examples slide decks
Each project contains:
@ -34,20 +34,20 @@ 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.
Images used in the documentation are located in the ``images`` directory.
The ``ql-training`` project contains the source files, themes, and static files
used to generate the QL training and variant analysis presentations.
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 QL training presentations** below.
**Building and previewing the CodeQL training presentations** below.
Building and previewing the QL language documentation
*****************************************************
Building and previewing the CodeQL documentation
************************************************
To build and preview the QL documentation and QL training presentations locally, you need to
To build and preview the documentation and training presentations locally, you need to
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.
@ -85,15 +85,15 @@ 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 QL training presentations
*****************************************************
Building and previewing the CodeQL training presentations
*********************************************************
To build the QL training presentations, you need to install a Sphinx extension
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 QL training presentations by running
After installing hieroglyph and graphviz, you can build the training presentations by running
``sphinx-build``, specifying the ``slides`` builder. For example
.. code::
@ -106,10 +106,10 @@ 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/Semmle/ql/blob/master/docs/language/ql-training/template.rst>`__.
Viewing the current version of the QL language documentation
************************************************************
Viewing the current version of the CodeQL documentation
*******************************************************
The QL language documentation for the most recent Semmle release is
The 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.
There, you can also find the documentation for the CodeQL CLI,
the CodeQL extension for Visual Studio Code, and LGTM Enterprise.