Merge pull request github#3178 from shati-patel/21-ql-language

shati-patel · web-flow · commit 48a09ce1c009 · 2020-04-01T16:07:17.000+01:00
[Migration prep] Docs: "QL language reference" category
diff --git a/docs/language/learn-ql/index.rst b/docs/language/learn-ql/index.rst
@@ -19,7 +19,6 @@ CodeQL is based on a powerful query language called QL. The following topics hel
    :maxdepth: 1
 
    introduction-to-ql
-   about-ql
    beginner/ql-tutorials
    writing-queries/writing-queries
    cpp/ql-for-cpp
diff --git a/docs/language/learn-ql/introduction-to-ql.rst b/docs/language/learn-ql/introduction-to-ql.rst
@@ -165,4 +165,4 @@ Learning CodeQL
 
 -  To find out more about how to write your own queries, try working through the :doc:`QL tutorials <beginner/ql-tutorials>`.
 -  For an overview of the other available resources, see :doc:`Learning CodeQL <../index>`.
--  For a more technical description of the underlying language, see :doc:`About QL <about-ql>`.
+-  For a more technical description of the underlying language, see the `QL language reference <https://help.semmle.com/QL/ql-handbook>`__
diff --git a/docs/language/learn-ql/writing-queries/debugging-queries.rst b/docs/language/learn-ql/writing-queries/debugging-queries.rst
@@ -10,7 +10,7 @@ This topic offers some simple tips on how to avoid common problems that can affe
 Before reading the tips below, it is worth reiterating a few important points about CodeQL and the QL language:
 
 - CodeQL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ are evaluated to database `tables <https://en.wikipedia.org/wiki/Table_(database)>`__. Large predicates generate large tables with many rows, and are therefore expensive to compute.
-- The QL language is implemented using standard database operations and `relational algebra <https://en.wikipedia.org/wiki/Relational_algebra>`__ (such as join, projection, and union). For further information about query languages and databases, see :doc:`About QL <../about-ql>`.
+- The QL language is implemented using standard database operations and `relational algebra <https://en.wikipedia.org/wiki/Relational_algebra>`__ (such as join, projection, and union). For further information about query languages and databases, see `About the QL language <https://help.semmle.com/QL/learn-ql/about-ql.html>`__.
 - Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see `Evaluation of QL programs <https://help.semmle.com/QL/ql-handbook/evaluation.html>`__ in the QL handbook. 
 
 Performance tips
diff --git a/docs/language/ql-handbook/about-the-ql-language.rst b/docs/language/ql-handbook/about-the-ql-language.rst
@@ -1,17 +1,15 @@
-About QL
-========
+About the QL language
+######################
 
-This section is aimed at users with a background in general purpose programming as well as in databases. For a basic introduction and information on how to get started, see :doc:`Introduction to QL <introduction-to-ql>` and :doc:`Learning CodeQL <../index>`.
-
-QL is a declarative, object-oriented query language that is optimized to enable efficient analysis of hierarchical data structures, in particular, databases representing software artifacts.
-
-The queries and metrics used in LGTM are implemented using CodeQL, which uses QL to analyze code. This ensures that they can be extended or revised easily to keep up with changes in definitions of best coding practice. We continually improve existing queries as we work towards the ultimate goal of 100% precision.
-
-You can write queries to identify security vulnerabilities, find coding errors and bugs, or find code that breaks your team's guidelines for best practice. You can also create customized versions of the default queries to accommodate a new framework.
+QL is the powerful query language that underlies CodeQL, which is used to analyze code.
 
 About query languages and databases
 -----------------------------------
 
+This section is aimed at users with a background in general purpose programming as well as in databases. For a basic introduction and information on how to get started, see `Learning CodeQL <https://help.semmle.com/QL/learn-ql/index.html>`__.
+
+QL is a declarative, object-oriented query language that is optimized to enable efficient analysis of hierarchical data structures, in particular, databases representing software artifacts.
+
 A database is an organized collection of data. The most commonly used database model is a relational model which stores data in tables and SQL (Structured Query Language) is the most commonly used query language for relational databases.
 
 The purpose of a query language is to provide a programming platform where you can ask questions about information stored in a database. A database management system manages the storage and administration of data and provides the querying mechanism. A query typically refers to the relevant database entities and specifies various conditions (called predicates) that must be satisfied by the results. Query evaluation involves checking these predicates and generating the results. Some of the desirable properties of a good query language and its implementation include:
@@ -41,6 +39,11 @@ When you write this process in QL, it closely resembles the above structure. Not
      result = count(getADescendant(p))
    }
 
+For more information about the important concepts and syntactic constructs of QL, see the individual reference topics such as :doc:`Expressions <expressions>` and :doc:`Recursion <recursion>`.
+The explanations and examples help you understand how the language works, and how to write more advanced QL code.
+
+For formal specifications of the QL language and QLDoc comments, see the :doc:`QL language specification <language>` and :doc:`QLDoc comment specification <qldoc>`.
+
 QL and object orientation
 -------------------------
 
@@ -56,12 +59,10 @@ Here are a few prominent conceptual and functional differences between general p
 -  QL's set-based semantics makes it very natural to process collections of values without having to worry about efficiently storing, indexing and traversing them.
 -  In object oriented programming languages, instantiating a class involves creating an object by allocating physical memory to hold the state of that instance of the class. In QL, classes are just logical properties describing sets of already existing values.
 
-These topics are discussed in detail in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__.
-
-References
-----------
+Further reading
+---------------
 
-Academic references available from the `Semmle website <https://help.semmle.com/publications.html>`__ also provide an overview of QL and its semantics. Other useful references on database query languages and Datalog:
+`Academic references <https://help.semmle.com/publications.html>`__ also provide an overview of QL and its semantics. Other useful references on database query languages and Datalog:
 
 -  `Database theory: Query languages <http://www.lsv.ens-cachan.fr/~segoufin/Papers/Mypapers/DB-chapter.pdf>`__
 -  `Logic Programming and Databases book - Amazon page <http://www.amazon.co.uk/Programming-Databases-Surveys-Computer-Science/dp/3642839541>`__
diff --git a/docs/language/ql-handbook/conf.py b/docs/language/ql-handbook/conf.py
@@ -41,7 +41,7 @@
 master_doc = 'index'
 
 # Project-specific information.
-project = u'QL language handbook'
+project = u'QL language reference'
 
 # The version info for this project, if different from version and release in main conf.py file.
 # The short X.Y version.
@@ -53,10 +53,10 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = 'QL language handbook'
+html_title = 'QL language reference'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'QL language handbook'
+htmlhelp_basename = 'QL language reference'
 
 # -- Currently unused, but potentially useful, configs--------------------------------------
 
diff --git a/docs/language/ql-handbook/index.rst b/docs/language/ql-handbook/index.rst
@@ -1,28 +1,12 @@
-QL language handbook
-####################
+QL language reference
+#####################
 
-Welcome to the QL language handbook! 
-
-This document describes the main features of the QL language. The explanations and examples
-help you understand how the language works, and how to write more advanced QL code.
-
-Each section describes an important concept or syntactic construct of QL. For an overview, see
-the table of contents below.
-
-If you are just getting started with QL, see `Learning CodeQL <https://help.semmle.com/QL/learn-ql/>`_
-for a list of the available resources.
-
-.. index:: specification
-
-For a formal specification of the QL language, see the `QL language specification
-<https://help.semmle.com/QL/ql-spec/language.html>`_.
-
-Table of contents
-*****************
+Learn all about QL, the powerful query language that underlies the code scanning tool CodeQL.
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 1
 
+   about-the-ql-language
    predicates
    queries
    types
@@ -36,9 +20,5 @@ Table of contents
    lexical-syntax
    name-resolution
    evaluation
-
-Index and search
-****************
-
-* :ref:`genindex`
-* :ref:`search`
+   language
+   qldoc
diff --git a/docs/language/ql-handbook/language.rst b/docs/language/ql-handbook/language.rst
@@ -3,6 +3,10 @@ QL language specification
 
 This is a formal specification for the QL language. It provides a comprehensive reference for terminology, syntax, and other technical details about QL.
 
+.. This ``highlight`` directive prevents code blocks in this file being highlighted as QL (the default language for this Sphinx project). 
+
+.. highlight:: none
+
 Introduction
 ------------
 
diff --git a/docs/language/ql-handbook/qldoc.rst b/docs/language/ql-handbook/qldoc.rst
diff --git a/docs/language/ql-spec/index.rst b/docs/language/ql-spec/index.rst
@@ -1,24 +1,5 @@
-QL specifications
-#################
+README
+######
 
-.. index:: specification
-
-
-For a formal specification of the QL language, including a description of syntax, terminology, and other technical details, please consult the QL language specification.
-
-For information on the terminology and syntax used in QLDoc comments, please consult the QLDoc comment specification.
-
-.. toctree::
-   :maxdepth: 2
-   
-   language
-
-   qldoc
-
-
-Search
-******
-
-.. * :ref:`genindex`
-
-* :ref:`search`
+The specifications have moved to ``ql/docs/language/ql-handbook``.
+See https://github.com/github/semmle-docs/issues/21 for details of the restructuring.
diff --git a/docs/language/ql-training/slide-snippets/intro-ql-general.rst b/docs/language/ql-training/slide-snippets/intro-ql-general.rst
@@ -124,7 +124,7 @@ QL is:
 
 .. note::
 
-  QL is the high-level, object-oriented logic language that underpins all CodeQL libraries and analyses. You can learn lots more about QL by visiting `Introduction to the QL language <https://help.semmle.com/QL/learn-ql/ql/introduction-to-ql.html>`__ and `About QL <https://help.semmle.com/QL/learn-ql/ql/about-ql.html>`__.
+  QL is the high-level, object-oriented logic language that underpins all CodeQL libraries and analyses. You can learn lots more about QL by visiting the `QL language reference <https://help.semmle.com/QL/ql-handbook>`__.
   The key features of QL are:
   
   - All common logic connectives are available, including quantifiers like ``exist``, which can also introduce new variables. 
