add intros and tweak tocs

2025-12-16 16:53:25 +01:00 · 2020-11-26 15:51:08 +00:00
parent b5626cbb70
commit d38e297ef9
35 changed files with 113 additions and 6 deletions
--- a/docs/codeql/codeql-cli/index.rst
+++ b/docs/codeql/codeql-cli/index.rst
@@ -5,8 +5,6 @@ CodeQL CLI

 .. include:: ../reusables/codeql-cli-overview.rst

-See the following links to learn how to get set up and run CodeQL commands:
-
 - :ref:`Using the CodeQL CLI <using-the-codeql-cli>`: Software 
  developers and security researchers can secure their code using the CodeQL CLI.

--- a/docs/codeql/codeql-for-visual-studio-code/about-codeql-for-visual-studio-code.rst
+++ b/docs/codeql/codeql-for-visual-studio-code/about-codeql-for-visual-studio-code.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _about-codeql-for-visual-studio-code:

 About CodeQL for Visual Studio Code
--- a/docs/codeql/codeql-for-visual-studio-code/analyzing-your-projects.rst
+++ b/docs/codeql/codeql-for-visual-studio-code/analyzing-your-projects.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _analyzing-your-projects:

 Analyzing your projects
--- a/docs/codeql/codeql-for-visual-studio-code/customizing-settings.rst
+++ b/docs/codeql/codeql-for-visual-studio-code/customizing-settings.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _customizing-settings:

 Customizing settings
--- a/docs/codeql/codeql-for-visual-studio-code/exploring-data-flow-with-path-queries.rst
+++ b/docs/codeql/codeql-for-visual-studio-code/exploring-data-flow-with-path-queries.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _exploring-data-flow-with-path-queries:

 Exploring data flow with path queries
--- a/docs/codeql/codeql-for-visual-studio-code/exploring-the-structure-of-your-source-code.rst
+++ b/docs/codeql/codeql-for-visual-studio-code/exploring-the-structure-of-your-source-code.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _exploring-the-structure-of-your-source-code:

 Exploring the structure of your source code
--- a/docs/codeql/codeql-for-visual-studio-code/index.rst
+++ b/docs/codeql/codeql-for-visual-studio-code/index.rst
@@ -5,8 +5,6 @@ CodeQL for Visual Studio Code

 The CodeQL extension for Visual Studio Code adds rich language support for CodeQL and allows you to easily find problems in codebases.

-See the following help topics for more information:
-
 - :doc:`About CodeQL for Visual Studio Code
  <about-codeql-for-visual-studio-code>`: CodeQL for Visual Studio
  Code is an extension that lets you write, run, and test CodeQL queries in Visual
--- a/docs/codeql/codeql-for-visual-studio-code/setting-up-codeql-in-visual-studio-code.rst
+++ b/docs/codeql/codeql-for-visual-studio-code/setting-up-codeql-in-visual-studio-code.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _setting-up-codeql-in-visual-studio-code:

 Setting up CodeQL in Visual Studio Code
--- a/docs/codeql/codeql-for-visual-studio-code/testing-codeql-queries-in-visual-studio-code.rst
+++ b/docs/codeql/codeql-for-visual-studio-code/testing-codeql-queries-in-visual-studio-code.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _testing-codeql-queries-in-visual-studio-code:

 Testing CodeQL queries in Visual Studio Code
--- a/docs/codeql/codeql-for-visual-studio-code/troubleshooting-codeql-for-visual-studio-code.rst
+++ b/docs/codeql/codeql-for-visual-studio-code/troubleshooting-codeql-for-visual-studio-code.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _troubleshooting-codeql-for-visual-studio-code:

 Troubleshooting CodeQL for Visual Studio Code
--- a/docs/codeql/codeql-language-guides/index.rst
+++ b/docs/codeql/codeql-language-guides/index.rst
@@ -3,6 +3,8 @@
 CodeQL language guides
 ======================

+Experiment and learn how to write effective and efficient queries for CodeQL databases generated from the languages supported in CodeQL analysis.
+
 .. toctree::

   codeql-for-cpp/index
--- a/docs/codeql/codeql-overview/about-codeql.rst
+++ b/docs/codeql/codeql-overview/about-codeql.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _about-codeql:

 About CodeQL
--- a/docs/codeql/codeql-overview/codeql-glossary.rst
+++ b/docs/codeql/codeql-overview/codeql-glossary.rst
@@ -1,9 +1,11 @@
+:tocdepth: 1
+
 .. _codeql-glossary:

 CodeQL glossary
 ===============

-An overview of the technical terms and concepts in coCodeQL. 
+An overview of the technical terms and concepts in CodeQL. 

 .. _bqrs-file:

--- a/docs/codeql/codeql-overview/codeql-tools.rst
+++ b/docs/codeql/codeql-overview/codeql-tools.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _codeql-tools:

 CodeQL tools
--- a/docs/codeql/codeql-overview/index.rst
+++ b/docs/codeql/codeql-overview/index.rst
@@ -3,8 +3,17 @@
 CodeQL overview
 ===============

+- :doc:`About CodeQL <about-codeql>`: CodeQL is the analysis engine used by developers to automate security checks, and by security researchers to perform variant analysis. 
+
+- :doc:`Supported languages and frameworks <supported-languages-and-frameworks>`: View the languages, libraries, and frameworks supported in the latest version of CodeQL.
+
+- :doc:`CodeQL tools <codeql-tools>`: GitHub provides the CodeQL command-line interface and CodeQL for Visual Studio Code for performing CodeQL analysis on open source codebases.
+
+- :doc:`CodeQL glossary <codeql-glossary>`: An overview of the technical terms and concepts in CodeQL. 
+
 .. toctree:: 
   :maxdepth: 1
+   :hidden:

   about-codeql
   supported-languages-and-frameworks
--- a/docs/codeql/codeql-overview/supported-languages-and-frameworks.rst
+++ b/docs/codeql/codeql-overview/supported-languages-and-frameworks.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _supported-languages-and-frameworks:

 Supported languages and frameworks
--- a/docs/codeql/index.rst
+++ b/docs/codeql/index.rst
@@ -2,7 +2,8 @@ CodeQL documentation
 ====================

 .. toctree::
-   :hidden:
+   :includehidden:
+   :maxdepth: 3
   
   codeql-overview/index
   codeql-for-visual-studio-code/index
--- a/docs/codeql/ql-language-reference/about-the-ql-language.rst
+++ b/docs/codeql/ql-language-reference/about-the-ql-language.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _about-the-ql-language:

 About the QL language
--- a/docs/codeql/ql-language-reference/aliases.rst
+++ b/docs/codeql/ql-language-reference/aliases.rst
@@ -1,4 +1,7 @@
+:tocdepth: 1
+
 .. index:: alias
+
 .. _aliases:

 Aliases
--- a/docs/codeql/ql-language-reference/annotations.rst
+++ b/docs/codeql/ql-language-reference/annotations.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _annotations:

 Annotations
--- a/docs/codeql/ql-language-reference/evaluation-of-ql-programs.rst
+++ b/docs/codeql/ql-language-reference/evaluation-of-ql-programs.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _evaluation-of-ql-programs:

 Evaluation of QL programs
--- a/docs/codeql/ql-language-reference/expressions.rst
+++ b/docs/codeql/ql-language-reference/expressions.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _expressions:

 Expressions
--- a/docs/codeql/ql-language-reference/formulas.rst
+++ b/docs/codeql/ql-language-reference/formulas.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _formulas:

 Formulas
--- a/docs/codeql/ql-language-reference/index.rst
+++ b/docs/codeql/ql-language-reference/index.rst
@@ -5,8 +5,41 @@ QL language reference

 Learn all about QL, the powerful query language that underlies the code scanning tool CodeQL.

+- :doc:`About the QL language <about-the-ql-language>`: QL is the powerful query language that underlies CodeQL, which is used to analyze code.
+
+- :doc:`Predicates <predicates>`: Predicates are used to describe the logical relations that make up a QL program. 
+
+- :doc:`Queries <queries>`: Queries are the output of a QL program. They evaluate to sets of results.
+
+- :doc:`Types <types>`: QL is a statically typed language, so each variable must have a declared type.
+
+- :doc:`Modules <modules>`: Modules provide a way of organizing QL code by grouping together related types, predicates, and other modules. 
+
+- :doc:`Aliases <aliases>`: An alias is an alternative name for an existing QL entity. 
+
+- :doc:`Variables <variables>`: Variables in QL are used in a similar way to variables in algebra or logic. They represent sets of values, and those values are usually restricted by a formula.
+
+- :doc:`Expressions <expressions>`: An expression evaluates to a set of values and has a type.
+
+- :doc:`Formulas <formulas>`: Formulas define logical relations between the free variables used in expressions.
+
+- :doc:`Annotations <annotations>`: An annotation is a string that you can place directly before the declaration of a QL entity or name.
+
+- :doc:`Recursion <recursion>`: QL provides strong support for recursion. A predicate in QL is said to be recursive if it depends, directly or indirectly, on itself. 
+
+- :doc:`Lexical syntax <lexical-syntax>`: The QL syntax includes different kinds of keywords, identifiers, and comments.
+
+- :doc:`Name resolution <name-resolution>`: The QL compiler resolves names to program elements.
+
+- :doc:`Evaluation of QL programs <evaluation-of-ql-programs>`: A QL program is evaluated in a number of different steps.
+
+- :doc:`QL language specification <ql-language-specification>`: A formal specification for the QL language. It provides a comprehensive reference for terminology, syntax, and other technical details about QL. 
+
+- :doc:`QLDoc comment specification <qldoc-comment-specification>`: a formal specification for QLDoc comments.
+
 .. toctree::
   :maxdepth: 1
+   :hidden:

   about-the-ql-language
   predicates
--- a/docs/codeql/ql-language-reference/lexical-syntax.rst
+++ b/docs/codeql/ql-language-reference/lexical-syntax.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _lexical-syntax:

 Lexical syntax
--- a/docs/codeql/ql-language-reference/modules.rst
+++ b/docs/codeql/ql-language-reference/modules.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _modules:

 Modules
--- a/docs/codeql/ql-language-reference/name-resolution.rst
+++ b/docs/codeql/ql-language-reference/name-resolution.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _name-resolution:

 Name resolution
--- a/docs/codeql/ql-language-reference/predicates.rst
+++ b/docs/codeql/ql-language-reference/predicates.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _predicates:

 Predicates
--- a/docs/codeql/ql-language-reference/ql-language-specification.rst
+++ b/docs/codeql/ql-language-reference/ql-language-specification.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _ql-language-specification:

 QL language specification
--- a/docs/codeql/ql-language-reference/qldoc-comment-specification.rst
+++ b/docs/codeql/ql-language-reference/qldoc-comment-specification.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _qldoc-comment-specification:

 QLDoc comment specification
--- a/docs/codeql/ql-language-reference/queries.rst
+++ b/docs/codeql/ql-language-reference/queries.rst
@@ -1,4 +1,7 @@
+:tocdepth: 1
+
 .. index:: query
+
 .. _queries:

 Queries
--- a/docs/codeql/ql-language-reference/recursion.rst
+++ b/docs/codeql/ql-language-reference/recursion.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. index:: recursion

 .. _recursion:
--- a/docs/codeql/ql-language-reference/types.rst
+++ b/docs/codeql/ql-language-reference/types.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. index:: type

 .. _types:
--- a/docs/codeql/ql-language-reference/variables.rst
+++ b/docs/codeql/ql-language-reference/variables.rst
@@ -1,4 +1,7 @@
+:tocdepth: 1
+
 .. index:: variable
+
 .. _variables:

 Variables
--- a/docs/codeql/writing-codeql-queries/index.rst
+++ b/docs/codeql/writing-codeql-queries/index.rst
@@ -3,7 +3,14 @@
 Writing CodeQL queries
 ======================

+Get to know more about queries and learn some key query-writing skills by solving puzzles.
+
+- :ref:`CodeQL <codeql-queries>`: CodeQL queries are used in code scanning analyses to find problems in source code, including potential security vulnerabilities.
+
+- :ref:`QL tutorials <ql-tutorials>`: Solve puzzles to learn the basics of QL before you analyze code with CodeQL. The tutorials teach you how to write queries and introduce you to key logic concepts along the way.
+
 .. toctree::
+   :hidden:

   ql-tutorials/index
   codeql-queries/index