Merge pull request #16496 from github/felicitymay/sphinx-config

felicitymay · web-flow · commit daf19a24687f · 2024-05-17T13:37:36.000+01:00
Stop building the CodeQL for VS Code docs now they've been migrated
diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst
@@ -408,7 +408,7 @@ Exercise 4
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/cpp-further-reading.rst
diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp.rst
@@ -380,7 +380,7 @@ Exercise 4
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/cpp-further-reading.rst
diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-csharp.rst
@@ -541,7 +541,7 @@ This can be adapted from the ``SystemUriFlow`` class:
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/csharp-further-reading.rst
diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-java.rst
@@ -3,7 +3,7 @@
 Analyzing data flow in Java and Kotlin
 ======================================
 
-You can use CodeQL to track the flow of data through a Java/Kotlin program to its use. 
+You can use CodeQL to track the flow of data through a Java/Kotlin program to its use.
 
 .. include:: ../reusables/kotlin-beta-note.rst
 
@@ -171,7 +171,7 @@ Global data flow tracks data flow throughout the entire program, and is therefor
 .. pull-quote:: Note
 
    .. include:: ../reusables/path-problem.rst
-   
+
 Using global data flow
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -362,7 +362,7 @@ Exercise 4
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/java-further-reading.rst
diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst
@@ -16,7 +16,7 @@ For a more general introduction to modeling data flow, see ":ref:`About data flo
 Data flow nodes
 ---------------
 
-Both local and global data flow, as well as taint tracking, work on a representation of the program known as the :ref:`data flow graph <data-flow-graph>`. 
+Both local and global data flow, as well as taint tracking, work on a representation of the program known as the :ref:`data flow graph <data-flow-graph>`.
 Nodes on the data flow flow graph may also correspond to nodes on the abstract syntax tree, but they are not the same.
 While AST nodes belong to class ``ASTNode`` and its subclasses, data flow nodes belong to class ``DataFlow::Node`` and its subclasses:
 
@@ -557,8 +557,8 @@ Exercise 4
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/java-further-reading.rst
-.. include:: ../reusables/codeql-ref-tools-further-reading.rst
+.. include:: ../reusables/codeql-ref-tools-further-reading.rst
diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-python.rst
@@ -359,7 +359,7 @@ This data flow configuration tracks data flow from environment variables to open
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/python-further-reading.rst
diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-ruby.rst
@@ -111,7 +111,7 @@ This query finds the filename argument passed in each call to ``File.open``:
 
     import codeql.ruby.DataFlow
     import codeql.ruby.ApiGraphs
-    
+
     from DataFlow::CallNode call
     where call = API::getTopLevelMember("File").getAMethodCall("open")
     select call.getArgument(0)
@@ -126,7 +126,7 @@ So we use local data flow to find all expressions that flow into the argument:
 
     import codeql.ruby.DataFlow
     import codeql.ruby.ApiGraphs
-    
+
     from DataFlow::CallNode call, DataFlow::ExprNode expr
     where
       call = API::getTopLevelMember("File").getAMethodCall("open") and
@@ -143,7 +143,7 @@ We can update the query to specify that ``expr`` is an instance of a ``LocalSour
 
     import codeql.ruby.DataFlow
     import codeql.ruby.ApiGraphs
-    
+
     from DataFlow::CallNode call, DataFlow::ExprNode expr
     where
       call = API::getTopLevelMember("File").getAMethodCall("open") and
@@ -158,7 +158,7 @@ That would allow us to use the member predicate ``flowsTo`` on ``LocalSourceNode
 
     import codeql.ruby.DataFlow
     import codeql.ruby.ApiGraphs
-    
+
     from DataFlow::CallNode call, DataFlow::ExprNode expr
     where
       call = API::getTopLevelMember("File").getAMethodCall("open") and
@@ -171,7 +171,7 @@ As an alternative, we can ask more directly that ``expr`` is a local source of t
 
     import codeql.ruby.DataFlow
     import codeql.ruby.ApiGraphs
-    
+
     from DataFlow::CallNode call, DataFlow::ExprNode expr
     where
       call = API::getTopLevelMember("File").getAMethodCall("open") and
@@ -190,7 +190,7 @@ This query finds instances where a parameter is used as the name when opening a
 
     import codeql.ruby.DataFlow
     import codeql.ruby.ApiGraphs
-    
+
     from DataFlow::CallNode call, DataFlow::ParameterNode p
     where
       call = API::getTopLevelMember("File").getAMethodCall("open") and
@@ -206,7 +206,7 @@ This query finds calls to ``File.open`` where the file name is derived from a pa
     import codeql.ruby.DataFlow
     import codeql.ruby.TaintTracking
     import codeql.ruby.ApiGraphs
-    
+
     from DataFlow::CallNode call, DataFlow::ParameterNode p
     where
       call = API::getTopLevelMember("File").getAMethodCall("open") and
@@ -327,17 +327,17 @@ The following global taint-tracking query finds path arguments in filesystem acc
     import codeql.ruby.TaintTracking
     import codeql.ruby.Concepts
     import codeql.ruby.dataflow.RemoteFlowSources
-    
+
     module RemoteToFileConfiguration implements DataFlow::ConfigSig {
       predicate isSource(DataFlow::Node source) { source instanceof RemoteFlowSource }
-    
+
       predicate isSink(DataFlow::Node sink) {
         sink = any(FileSystemAccess fa).getAPathArgument()
       }
     }
 
     module RemoteToFileFlow = TaintTracking::Global<RemoteToFileConfiguration>;
-    
+
     from DataFlow::Node input, DataFlow::Node fileAccess
     where RemoteToFileFlow::flow(input, fileAccess)
     select fileAccess, "This file access uses data from $@.", input, "user-controllable input."
@@ -352,7 +352,7 @@ The following global data-flow query finds calls to ``File.open`` where the file
     import codeql.ruby.DataFlow
     import codeql.ruby.controlflow.CfgNodes
     import codeql.ruby.ApiGraphs
-    
+
     module EnvironmentToFileConfiguration implements DataFlow::ConfigSig {
       predicate isSource(DataFlow::Node source) {
         exists(ExprNodes::ConstantReadAccessCfgNode env |
@@ -367,7 +367,7 @@ The following global data-flow query finds calls to ``File.open`` where the file
     }
 
     module EnvironmentToFileFlow = DataFlow::Global<EnvironmentToFileConfiguration>;
-    
+
     from DataFlow::Node environment, DataFlow::Node fileOpen
     where EnvironmentToFileFlow::flow(environment, fileOpen)
     select fileOpen, "This call to 'File.open' uses data from $@.", environment,
@@ -376,7 +376,7 @@ The following global data-flow query finds calls to ``File.open`` where the file
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/ruby-further-reading.rst
diff --git a/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst b/docs/codeql/codeql-language-guides/analyzing-data-flow-in-swift.rst
@@ -34,7 +34,7 @@ The ``Node`` class has a number of useful subclasses, such as ``ExprNode`` for e
        Expr asExpr() { ... }
 
        /**
-        * Gets the control flow node that corresponds to this data flow node. 
+        * Gets the control flow node that corresponds to this data flow node.
         */
        ControlFlowNode getCfgNode() { ... }
 
@@ -284,7 +284,7 @@ The following global taint-tracking query finds places where a value from a remo
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/swift-further-reading.rst
diff --git a/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst b/docs/codeql/codeql-language-guides/customizing-library-models-for-java-and-kotlin.rst
@@ -16,7 +16,8 @@ This article contains reference material about how to define custom models for s
 
 The best way to create your own models is using the CodeQL model editor in the CodeQL extension for Visual Studio Code. The model editor automatically guides you through the process of defining models, displaying the properties you need to define and the options available. You can save the resulting models as data extension files in CodeQL model packs and use them without worrying about the syntax.
 
-For more information, see ":ref:`Using the CodeQL model editor <using-the-codeql-model-editor>`."
+For more information, see `Using the CodeQL model editor  <https://docs.github.com/en/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor>`__ in the GitHub documentation.
+
 
 About data extensions
 ---------------------
diff --git a/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst b/docs/codeql/codeql-language-guides/data-flow-cheat-sheet-for-javascript.rst
@@ -254,8 +254,8 @@ Troubleshooting
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/javascript-further-reading.rst
-.. include:: ../reusables/codeql-ref-tools-further-reading.rst
+.. include:: ../reusables/codeql-ref-tools-further-reading.rst
diff --git a/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst b/docs/codeql/codeql-language-guides/using-flow-labels-for-precise-data-flow-analysis.rst
@@ -405,7 +405,7 @@ string may be an absolute path and whether it may contain ``..`` components.
 Further reading
 ---------------
 
-- ":ref:`Exploring data flow with path queries <exploring-data-flow-with-path-queries>`"
+- `Exploring data flow with path queries  <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries>`__ in the GitHub documentation.
 
 
 .. include:: ../reusables/javascript-further-reading.rst
diff --git a/docs/codeql/codeql-overview/codeql-glossary.rst b/docs/codeql/codeql-overview/codeql-glossary.rst
@@ -61,7 +61,7 @@ The DIL format may change without warning between CLI releases.
 When you specify the ``--dump-dil`` option for ``codeql query compile``, CodeQL
 prints DIL to standard output for the queries it compiles. You can also
 view results in DIL format when you run queries in VS Code.
-For more information, see ":ref:`Analyzing your projects <viewing-query-results>`" in the CodeQL for VS Code help.
+For more information, see `Running CodeQL queries <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries#understanding-your-query-results>`__ in the GitHub documentation.
 
 .. _extractor:
 
diff --git a/docs/codeql/conf.py b/docs/codeql/conf.py
@@ -2,13 +2,13 @@
 #
 # The Sphinx config values used in the CodeQL documentation that is published
 # at codeql.github.com/docs
-# 
+#
 # Note that not all possible configuration values are present in this file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 #
-# For details of all possible config values, 
+# For details of all possible config values,
 # see https://www.sphinx-doc.org/en/master/usage/configuration.html
 #
 # -- GENERAL CONFIG VALUES ------------------------------------------------
@@ -53,7 +53,7 @@
 
 
 def setup(sphinx):
-    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))	
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
     from qllexer import QLLexer
     sphinx.add_lexer("ql", QLLexer() if sphinx_mod.version_info[0] <= 3 else QLLexer)
 
@@ -86,7 +86,7 @@ def setup(sphinx):
 
 # HTML theme options used to customize the look and feel of the docs.
 html_theme_options = {'font_size': '16px',
-                      'body_text': '#333', 
+                      'body_text': '#333',
                       'link': '#2F1695',
                       'link_hover': '#2F1695',
                       'show_powered_by': False,
@@ -106,4 +106,4 @@ def setup(sphinx):
 html_favicon = 'images/site/favicon.ico'
 
 # Exclude these paths from being built by Sphinx
-exclude_patterns = ['vale*', '_static', '_templates', 'reusables', 'images', 'support', 'ql-training', 'query-help', '_build', '*.py*', 'README.rst']
+exclude_patterns = ['vale*', '_static', '_templates', 'reusables', 'images', 'support', 'ql-training', 'query-help', '_build', '*.py*', 'README.rst', 'codeql-for-visual-studio-code']
diff --git a/docs/codeql/contents.rst b/docs/codeql/contents.rst
@@ -6,7 +6,6 @@ CodeQL documentation
    :maxdepth: 3
 
    codeql-overview/index
-   codeql-for-visual-studio-code/index
    writing-codeql-queries/index
    codeql-language-guides/index
    ql-language-reference/index
diff --git a/docs/codeql/reusables/codespaces-template-note.rst b/docs/codeql/reusables/codespaces-template-note.rst
@@ -3,6 +3,5 @@
    Note
 
    You can use the CodeQL template (beta) in `GitHub Codespaces <https://github.com/codespaces/new?template_repository=github/codespaces-codeql>`__ to try out the QL concepts and programming-language-agnostic examples in these tutorials. The template includes a guided introduction to working with QL, and makes it easy to get started.
-   
-   When you're ready to run CodeQL queries on actual codebases, you will need to install the CodeQL extension in Visual Studio Code. For instructions, see ":ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`."
-   
+
+   When you're ready to run CodeQL queries on actual codebases, you will need to install the CodeQL extension in Visual Studio Code. For instructions, see `Installing CodeQL for Visual Studio Code <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code>`__ in the GitHub documentation.
diff --git a/docs/codeql/reusables/setup-to-run-tutorials.rst b/docs/codeql/reusables/setup-to-run-tutorials.rst
@@ -1 +1 @@
-For information about installing the CodeQL extension for Visual Studio code, see ":ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`."
+For information about installing the CodeQL extension for Visual Studio code, see `Installing CodeQL for Visual Studio Code <https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code>`__ in the GitHub documentation.
diff --git a/docs/codeql/writing-codeql-queries/about-codeql-queries.rst b/docs/codeql/writing-codeql-queries/about-codeql-queries.rst
diff --git a/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst b/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst
diff --git a/docs/codeql/writing-codeql-queries/creating-path-queries.rst b/docs/codeql/writing-codeql-queries/creating-path-queries.rst
diff --git a/docs/codeql/writing-codeql-queries/debugging-data-flow-queries-using-partial-flow.rst b/docs/codeql/writing-codeql-queries/debugging-data-flow-queries-using-partial-flow.rst
diff --git a/docs/codeql/writing-codeql-queries/introduction-to-ql.rst b/docs/codeql/writing-codeql-queries/introduction-to-ql.rst
