Merge pull request #4874 from shati-patel/docs-highlighting

Docs: Tweak syntax highlighting

Author: shati-patel

docs/codeql/codeql-language-guides/codeql-library-for-csharp.rst

@@ -108,8 +108,8 @@ Count the number of lines of code, excluding the directory ``external``:
 .. code-block:: ql
 
    select sum(SourceFile f |
-     not exists(Folder external | external.getShortName() = "external" |
-                external.getAFolder*().getAFile() = f) |
+     not exists(Folder ext | ext.getShortName() = "external" |
+                ext.getAFolder*().getAFile() = f) |
      f.getNumberOfLines())
 
 Exercises
@@ -961,7 +961,7 @@ Find all obsolete elements:
 
 Model NUnit test fixtures:
 
-.. code-block:: csharp
+.. code-block:: ql
 
    class TestFixture extends Class
    {

docs/codeql/conf.py

@@ -39,6 +39,12 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# The default language for syntax highlighting. We need to explicitly set this to "none",
+# otherwise Sphinx tries to highlight any unlabeled code samples as "python3".
+# See https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-highlight_language.
+
+highlight_language = "none"
+
 # Import the QL Lexer to use for syntax highlighting
 import os
 import sys

docs/codeql/ql-language-reference/aliases.rst

@@ -33,7 +33,9 @@ to the name that it aliases.
 Module aliases
 ==============
 
-Use the following syntax to define an alias for a :ref:`module <modules>`::
+Use the following syntax to define an alias for a :ref:`module <modules>`:
+
+.. code-block:: ql
 
     module ModAlias = ModuleName;
 
@@ -52,14 +54,18 @@ a deprecation warning is displayed.
 Type aliases
 ============
 
-Use the following syntax to define an alias for a :ref:`type <types>`::
+Use the following syntax to define an alias for a :ref:`type <types>`:
+
+.. code-block:: ql
 
     class TypeAlias = TypeName;
 
 Note that ``class`` is just a keyword. You can define an alias for any type—namely, :ref:`primitive types <primitive-types>`,
 :ref:`database types <database-types>` and user-defined :ref:`classes <classes>`.
 
-For example, you can use an alias to abbreviate the name of the primitive type ``boolean`` to ``bool``::
+For example, you can use an alias to abbreviate the name of the primitive type ``boolean`` to ``bool``:
+
+.. code-block:: ql
 
     class bool = boolean;
 
@@ -80,21 +86,27 @@ Or, to use a class ``OneTwo`` defined in a :ref:`module <explicit-modules>` ``M`
 Predicate aliases
 =================
 
-Use the following syntax to define an alias for a :ref:`non-member predicate <non-member-predicates>`::
+Use the following syntax to define an alias for a :ref:`non-member predicate <non-member-predicates>`:
+
+.. code-block:: ql
 
     predicate PredAlias = PredicateName/Arity;
 
 This works for predicates :ref:`with <predicates-with-result>` or :ref:`without <predicates-without-result>` result. 
 
 For example, suppose you frequently use the following predicate, which calculates the successor of a positive integer 
-less than ten::
+less than ten:
+
+.. code-block:: ql
     
     int getSuccessor(int i) {
       result = i + 1 and
       i in [1 .. 9]
     }
     
-You can use an alias to abbreviate the name to ``succ``::
+You can use an alias to abbreviate the name to ``succ``:
+
+.. code-block:: ql
 
     predicate succ = getSuccessor/1;
 

docs/codeql/ql-language-reference/annotations.rst

@@ -83,7 +83,9 @@ to describe specific configurations. Any non-abstract subtypes must override it
 indirectly) to describe what sources of data they each track.
 
 In other words, all non-abstract classes that extend ``Configuration`` must override ``isSource`` in their
-own body, or they must inherit from another class that overrides ``isSource``::
+own body, or they must inherit from another class that overrides ``isSource``:
+
+.. code-block:: ql
 
     class ConfigA extends Configuration {
       ...
@@ -329,8 +331,10 @@ When you use this annotation, be aware of the following issues:
    In particular, you can't chain predicate :ref:`calls <calls>` or call predicates on a
    :ref:`cast <casts>`. You must write them as multiple conjuncts and explicitly order them.
 
-   For example, suppose you have the following definitions::
-   
+   For example, suppose you have the following definitions:
+
+   .. code-block:: ql
+
        class Small extends int {
          Small() { this in [1 .. 10] }
          Small getSucc() { result = this + 1}
@@ -344,8 +348,10 @@ When you use this annotation, be aware of the following issues:
          s.getSucc().getSucc() = 3
        }
    
-   If you add ``noopt`` pragmas, you must rewrite the predicates. For example::
-   
+   If you add ``noopt`` pragmas, you must rewrite the predicates. For example:
+
+   .. code-block:: ql
+
        pragma[noopt]
        predicate p(int i) {
          exists(Small s | s = i and s.getSucc() = 2)

docs/codeql/ql-language-reference/evaluation-of-ql-programs.rst

@@ -48,21 +48,27 @@ Here are some common ways that you might define infinite predicates. These all g
 compilation errors:
 
 - The following query conceptually selects all values of type ``int``, without restricting them.
-  The QL compiler returns the error ``'i' is not bound to a value``::
+  The QL compiler returns the error ``'i' is not bound to a value``:
+
+  .. code-block:: ql
   
       from int i
       select i
 
 - The following predicate generates two errors: ``'n' is not bound to a value`` and ``'result' is
-  not bound to a value``::
+  not bound to a value``:
 
+  .. code-block:: ql
+
       int timesTwo(int n) {
         result = n * 2
       }
 
 - The following class ``Person`` contains all strings that start with ``"Peter"``. There are
   infinitely many such strings, so this is another invalid definition. The QL compiler gives the
-  error message ``'this' is not bound to a value``::
+  error message ``'this' is not bound to a value``:
+  
+  .. code-block:: ql
   
       class Person extends string {
         Person() {

docs/codeql/ql-language-reference/expressions.rst

@@ -37,15 +37,17 @@ You can express certain values directly in QL, such as numbers, booleans, and st
   possibly starting with a minus sign (``-``).
   For example:
 
-.. code-block:: ql
+  .. code-block:: ql
 
     0
     42
     -2048 
 
 - :ref:`Float <float>` literals: These are sequences of decimal digits separated by a dot 
   (``.``), possibly starting with a minus sign (``-``).
-  For example::
+  For example:
+  
+  .. code-block:: ql
       
     2.0
     123.456
@@ -56,7 +58,7 @@ You can express certain values directly in QL, such as numbers, booleans, and st
   characters represent themselves, but there are a few characters that you need to "escape"
   with a backslash. The following are examples of string literals:
 
-.. code-block:: ql
+  .. code-block:: ql
 
     "hello"
     "They said, \"Please escape quotation marks!\""
@@ -135,7 +137,7 @@ In the following example, the class ``C`` inherits two definitions of the predic
 ``getANumber()``—one from ``A`` and one from ``B``. 
 Instead of overriding both definitions, it uses the definition from ``B``.
 
-::
+.. code-block:: ql
    
     class A extends int {
       A() { this = 1 }
@@ -213,7 +215,7 @@ The following aggregates are available in QL:
   For example, the following aggregation returns the number of files that have more than 
   ``500`` lines:
 
-.. code-block:: ql
+  .. code-block:: ql
 
       count(File f | f.getTotalNumberOfLines() > 500 | f)
   
@@ -229,15 +231,15 @@ The following aggregates are available in QL:
   For example, the following aggregation returns the name of the ``.js`` file (or files) with the 
   largest number of lines:
 
-.. code-block:: ql
+  .. code-block:: ql
 
       max(File f | f.getExtension() = "js" | f.getBaseName() order by f.getTotalNumberOfLines())
 
   The following aggregation returns the minimum string ``s`` out of the three strings mentioned
   below, that is, the string that comes first in the lexicographic ordering of all the possible
   values of ``s``. (In this case, it returns ``"De Morgan"``.)
 
-  ::
+  .. code-block:: ql
 
       min(string s | s = "Tarski" or s = "Dedekind" or s = "De Morgan" | s)
 
@@ -249,7 +251,9 @@ The following aggregates are available in QL:
   returns no values. In other words, it evaluates to the empty set.
 
   For example, the following aggregation returns the average of the integers ``0``, ``1``,
-  ``2``, and ``3``::
+  ``2``, and ``3``:
+
+  .. code-block:: ql
 
       avg(int i | i = [0 .. 3] | i)
 
@@ -260,7 +264,9 @@ The following aggregates are available in QL:
   If there are no possible assignments to the aggregation variables that satisfy the formula, then the sum is ``0``.
 
   For example, the following aggregation returns the sum of ``i * j`` for all possible values
-  of ``i`` and ``j``::
+  of ``i`` and ``j``:
+
+  .. code-block:: ql
 
       sum(int i, int j | i = [0 .. 2] and j = [3 .. 5] | i * j)
 
@@ -274,14 +280,16 @@ The following aggregates are available in QL:
   For example, the following aggregation returns the string ``"3210"``, that is, the
   concatenation of the strings ``"0"``, ``"1"``, ``"2"``, and ``"3"`` in descending order:
 
-.. code-block:: ql
+  .. code-block:: ql
 
       concat(int i | i = [0 .. 3] | i.toString() order by i desc)
 
   The ``concat`` aggregate can also take a second expression, separated from the first one by
   a comma. This second expression is inserted as a separator between each concatenated value.
 
-  For example, the following aggregation returns ``"0|1|2|3"``::
+  For example, the following aggregation returns ``"0|1|2|3"``:
+
+  .. code-block:: ql
 
       concat(int i | i = [0 .. 3] | i.toString(), "|")
 
@@ -294,7 +302,9 @@ The following aggregates are available in QL:
 
   For example, the following aggregation returns the value that is ranked 4th out of all the
   possible values. In this case, ``8`` is the 4th integer in the range from ``5`` through
-  ``15``::
+  ``15``:
+
+  .. code-block:: ql
 
       rank[4](int i | i = [5 .. 15] | i)
 
@@ -317,7 +327,9 @@ The following aggregates are available in QL:
 
   For example, the following query returns the positive integers ``1``, ``2``, ``3``, ``4``, ``5``.
   For negative integers ``x``, the expressions ``x`` and ``x.abs()`` have different values, so the
-  value for ``y`` in the aggregate expression is not uniquely determined. ::
+  value for ``y`` in the aggregate expression is not uniquely determined.
+
+  .. code-block:: ql
 
       from int x
       where x in [-5 .. 5] and x != 0
@@ -394,48 +406,54 @@ aggregation in a simpler form:
    then you can omit the ``<variable declarations>`` and ``<formula>`` parts and write it 
    as follows:
 
-.. code-block:: ql
+   .. code-block:: ql
 
        <aggregate>(<expression>)
 
    For example, the following aggregations determine how many times the letter ``l`` occurs in
-   string ``"hello"``. These forms are equivalent::
+   string ``"hello"``. These forms are equivalent:
+
+   .. code-block:: ql
    
        count(int i | i = "hello".indexOf("l") | i)
        count("hello".indexOf("l"))
 
-#. If there only one aggregation variable, you can omit the ``<expression>`` part instead.
+#. If there is only one aggregation variable, you can omit the ``<expression>`` part instead.
    In this case, the expression is considered to be the aggregation variable itself.
-   For example, the following aggregations are equivalent::
-   
+   For example, the following aggregations are equivalent:
+
+   .. code-block:: ql
+
        avg(int i | i = [0 .. 3] | i)
        avg(int i | i = [0 .. 3])
    
 #. As a special case, you can omit the ``<expression>`` part from ``count`` even if there is more
    than one aggregation variable. In such a case, it counts the number of distinct tuples of
    aggregation variables that satisfy the formula. In other words, the expression part is
-   considered to be the constant ``1``. For example, the following aggregations are equivalent::
-   
+   considered to be the constant ``1``. For example, the following aggregations are equivalent:
+
+   .. code-block:: ql
+  
        count(int i, int j | i in [1 .. 3] and j in [1 .. 3] | 1)
        count(int i, int j | i in [1 .. 3] and j in [1 .. 3])
 
 #. You can omit the ``<formula>`` part, but in that case you should include two vertical bars:
 
-.. code-block:: ql
+   .. code-block:: ql
 
        <aggregate>(<variable declarations> | | <expression>)
 
    This is useful if you don't want to restrict the aggregation variables any further. 
    For example, the following aggregation returns the maximum number of lines across all files:
 
-.. code-block:: ql
+   .. code-block:: ql
 
        max(File f | | f.getTotalNumberOfLines())
 
 #. Finally, you can also omit both the ``<formula>`` and ``<expression>`` parts. For example,
    the following aggregations are equivalent ways to count the number of files in a database:
 
-.. code-block:: ql
+   .. code-block:: ql
 
        count(File f | any() | 1)
        count(File f | | 1)
@@ -638,7 +656,9 @@ is exactly equivalent to ``((Foo)x)``.
 Casts are useful if you want to call a :ref:`member predicate <member-predicates>` that is only defined for a more 
 specific type. For example, the following query selects Java 
 `classes <https://codeql.github.com/codeql-standard-libraries/java/semmle/code/java/Type.qll/type.Type$Class.html>`_
-that have a direct supertype called "List":: 
+that have a direct supertype called "List":
+
+.. code-block:: ql
 
     import java
     
@@ -669,7 +689,9 @@ Unlike other expressions, a don't-care expression does not have a type. In pract
 means that ``_`` doesn't have any :ref:`member predicates <member-predicates>`, so you can't
 call ``_.somePredicate()``.
 
-For example, the following query selects all the characters in the string ``"hello"``::
+For example, the following query selects all the characters in the string ``"hello"``:
+
+.. code-block:: ql
 
     from string s
     where s = "hello".charAt(_)