Merge pull request github#4734 from github/sd-263

jf205 · web-flow · commit 4d8983830eac · 2020-11-30T14:06:21.000Z
[Docs] Add missing introduction text and improve sidebar toc
diff --git 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.
 
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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:
 
diff --git 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
diff --git a/docs/codeql/codeql-overview/index.rst b/docs/codeql/codeql-overview/index.rst
@@ -3,8 +3,19 @@
 CodeQL overview
 ===============
 
+Learn more about how CodeQL works, the languages and libraries supported by CodeQL analysis, and the tools you can use to run CodeQL on open source projects.
+
+- :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
diff --git 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
diff --git a/docs/codeql/conf.py b/docs/codeql/conf.py
@@ -27,7 +27,7 @@
 source_suffix = '.rst'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'contents'
 
 # General information about the project.
 project = u'CodeQL documentation'
diff --git a/docs/codeql/contents.rst b/docs/codeql/contents.rst
@@ -2,7 +2,8 @@ CodeQL documentation
 ====================
 
 .. toctree::
-   :hidden:
+   :includehidden:
+   :maxdepth: 3
    
    codeql-overview/index
    codeql-for-visual-studio-code/index
diff --git 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
diff --git 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
diff --git a/docs/codeql/ql-language-reference/annotations.rst b/docs/codeql/ql-language-reference/annotations.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _annotations:
 
 Annotations
diff --git 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
diff --git a/docs/codeql/ql-language-reference/expressions.rst b/docs/codeql/ql-language-reference/expressions.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _expressions:
 
 Expressions
diff --git a/docs/codeql/ql-language-reference/formulas.rst b/docs/codeql/ql-language-reference/formulas.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _formulas:
 
 Formulas
diff --git 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
@@ -23,4 +56,4 @@ Learn all about QL, the powerful query language that underlies the code scanning
    name-resolution
    evaluation-of-ql-programs
    ql-language-specification
-   qldoc-comment-specification
+   qldoc-comment-specification
diff --git 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
diff --git a/docs/codeql/ql-language-reference/modules.rst b/docs/codeql/ql-language-reference/modules.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _modules:
 
 Modules
diff --git 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
diff --git a/docs/codeql/ql-language-reference/predicates.rst b/docs/codeql/ql-language-reference/predicates.rst
@@ -1,3 +1,5 @@
+:tocdepth: 1
+
 .. _predicates:
 
 Predicates
diff --git 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
diff --git 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
diff --git 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
diff --git 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:
diff --git 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:
diff --git 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
diff --git 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 queries <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
+   codeql-queries/index

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:tocdepth: 1`
	`2`	`+`
`1`	`3`	`.. _about-codeql-for-visual-studio-code:`
`2`	`4`
`3`	`5`	`About CodeQL for Visual Studio Code`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:tocdepth: 1`
	`2`	`+`
`1`	`3`	`.. _analyzing-your-projects:`
`2`	`4`
`3`	`5`	`Analyzing your projects`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:tocdepth: 1`
	`2`	`+`
`1`	`3`	`.. _customizing-settings:`
`2`	`4`
`3`	`5`	`Customizing settings`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:tocdepth: 1`
	`2`	`+`
`1`	`3`	`.. _exploring-data-flow-with-path-queries:`
`2`	`4`
`3`	`5`	`Exploring data flow with path queries`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:tocdepth: 1`
	`2`	`+`
`1`	`3`	`.. _exploring-the-structure-of-your-source-code:`
`2`	`4`
`3`	`5`	`Exploring the structure of your source code`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:tocdepth: 1`
	`2`	`+`
`1`	`3`	`.. _setting-up-codeql-in-visual-studio-code:`
`2`	`4`
`3`	`5`	`Setting up CodeQL in Visual Studio Code`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:tocdepth: 1`
	`2`	`+`
`1`	`3`	`.. _testing-codeql-queries-in-visual-studio-code:`
`2`	`4`
`3`	`5`	`Testing CodeQL queries in Visual Studio Code`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:tocdepth: 1`
	`2`	`+`
`1`	`3`	`.. _troubleshooting-codeql-for-visual-studio-code:`
`2`	`4`
`3`	`5`	`Troubleshooting CodeQL for Visual Studio Code`