Merge pull request #1641 from jf205/move-ql-docs

Docs: add QL language documentation to `semmle/ql` repo

Author: Felicity Chapman

docs/ql-documentation/.gitignore

@@ -0,0 +1,2 @@
+# VSCode rst extension build directory
+**/_build/

docs/ql-documentation/.vale.ini

@@ -0,0 +1,42 @@
+# Vale configuration for the QL documentation
+# https://errata-ai.github.io/vale/
+
+# Core properties
+#----------------
+# Specify where to find styles
+StylesPath = vale-styles
+
+# Specify the minimum alert level to report
+# Alerts are assigned a level of suggestion, warning, or error.
+# For local use it's good to see all the suggestions and warnings.
+MinAlertLevel = suggestions
+
+# Specify how to test a particular type of files
+#-----------------------------------------------
+[*.{rst,csv}]
+
+# Vale comes with three built-in styles: write-good, proselint, and Joblint.
+# You could enable all rules in the "Microsoft" style guide as follows:
+# BasedOnStyles = Microsoft
+BasedOnStyles = Semmle
+
+# Initially, we only want to run a few rules, so we'll specify them individually
+# Style.Rule = {YES, NO} to enable or disable a specific rule
+Microsoft.DateFormat = YES
+Microsoft.DateNumbers = YES
+Microsoft.DateOrder = YES
+Microsoft.Foreign = YES
+Microsoft.Gender = YES
+Microsoft.OxfordComma = YES
+Microsoft.Quotes = YES
+Microsoft.Semicolon = YES
+Microsoft.SentenceLength = YES
+Microsoft.URLFormat = YES
+Microsoft.Wordiness = YES
+
+# This rule should never be run, it's replaced by a Semmle rule of the same name.
+Microsoft.Headings = NO
+
+# Modify the level of some rules
+Microsoft.Wordiness = suggestion
+Microsoft.OxfordComma = error

docs/ql-documentation/README.rst

@@ -0,0 +1,88 @@
+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.