address docs review comments

Author: james

.github/workflows/generate-query-help-docs.yml

@@ -47,7 +47,7 @@ jobs:
       with:
         docs-folder: "query-help/"
         pre-build-command: "python -m pip install --upgrade recommonmark"
-        build-command: "sphinx-build -b html . _build" 
+        build-command: "sphinx-build -b dirhtml . _build" 
     - name: Upload HTML artifacts
       uses: actions/upload-artifact@v2
       with:

docs/codeql/query-help/conf.py

@@ -57,4 +57,4 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 
-exclude_patterns = ['toc-*'] # ignore toc-<lang>.rst files as they are 'included' in index pages
+exclude_patterns = ['toc-*', 'readme.md'] # ignore toc-<lang>.rst files as they are 'included' in index pages

docs/codeql/query-help/cpp.rst

@@ -1,5 +1,5 @@
-C and C++ query help
-=====================
+CodeQL query help for C and C++
+===============================
 
 .. include:: ../reusables/query-help-overview.rst
 

docs/codeql/query-help/csharp.rst

@@ -1,5 +1,5 @@
-C# query help
-=============
+CodeQL query help for C#
+========================
 
 .. include:: ../reusables/query-help-overview.rst
 

docs/codeql/query-help/go.rst

@@ -1,5 +1,5 @@
-Go query help
-=============
+CodeQL query help for Go
+========================
 
 .. include:: ../reusables/query-help-overview.rst
 

docs/codeql/query-help/index.rst

@@ -3,16 +3,27 @@ CodeQL query help
 
 View the query help for the queries included in the ``code-scanning``, ``security-extended``, and ``security-and-quality`` query suites for the languages supported by CodeQL.
 
-Each query help article includes: 
+- :doc:`CodeQL query help for C and C++ <cpp>`
+- :doc:`CodeQL query help for C# <csharp>`
+- :doc:`CodeQL query help for Go <go>`
+- :doc:`CodeQL query help for Java <java>`
+- :doc:`CodeQL query help for JavaScript <javascript>`
+- :doc:`CodeQL query help for Python <python>`
 
-- A summary of key metadata for the query.
-- Information about which query suites the query is included in.
-- A link to the query in the `CodeQL repository <https://github.com/github/codeql>`__.
-- A description of the potential vulnerability that the query identifies and a recommendation for how to avoid introducing the problem to your code.
+
+.. pull-quote:: Information
+
+   Each query help article includes: 
+   
+   - A summary of key metadata for the query.
+   - Information about which query suites the query is included in.
+   - A link to the query in the `CodeQL repository <https://github.com/github/codeql>`__.
+   - A description of the potential vulnerability that the query identifies and a recommendation for how to avoid introducing the problem to your code.
 
 .. toctree::
+   :hidden:
    :titlesonly:
-
+   
    cpp
    csharp
    go

docs/codeql/query-help/java.rst

@@ -1,5 +1,5 @@
-Java query help
-===============
+CodeQL query help for Java query
+================================
 
 .. include:: ../reusables/query-help-overview.rst
 

docs/codeql/query-help/javascript.rst

@@ -1,5 +1,5 @@
-JavaScript query help
-=====================
+CodeQL query help for JavaScript
+================================
 
 .. include:: ../reusables/query-help-overview.rst
 

docs/codeql/query-help/python.rst

@@ -1,5 +1,5 @@
-Python query help
-=================
+CodeQL query help for Python
+============================
 
 .. include:: ../reusables/query-help-overview.rst