<commit_before>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.

Using ``sphinx-build``
----------------------
<commit_msg>docs: specify sphinx 1.7.9 in readme<commit_after>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 and QL training presentations locally, you need to 
install Sphinx 1.7.9. More recent versions of Sphinx do not work with hieoroglyph, 
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``
----------------------

{'fraction_non_alphanumeric': 0.12593703148425786, 'fraction_numerical': 0.001285071749839366, 'mean_word_length': 4.737100737100737, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 8, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4976959', 'n_tokens_mistral': 1228, 'n_tokens_neox': 1182, 'n_words': 533}