improve docs

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

@@ -1,4 +1,4 @@
-name: Generate CodeQL documentation using Sphinx
+name: Generate CodeQL query help documentation using Sphinx
 
 on:
   push:

docs/language/query-help-markdown.py

@@ -5,11 +5,24 @@ import csv
 import sys
 import os
 
+"""
+This script collects CodeQL queries that are part of code scanning query packs,
+renders the accompanying query help as markdown, inserts some useful metadata
+into the help, and adds a link to the query in the CodeQL repo.
+
+This script requires that 'git' and 'codeql' commands
+are on the PATH. It'll try to automatically set the CodeQL search path correctly,
+as long as you run the script from one of the following locations:
+ - anywhere from within a clone of the CodeQL Git repo
+ - from the parent directory of a clone of the CodeQL Git repo (assuming 'codeql' 
+   and 'codeql-go' directories both exist)
+"""
+
 # Define which languages and query packs to consider
 languages = [ "cpp", "csharp", "go", "java", "javascript", "python"]
 
-# Running generate query-help with "security-and-quality.qls" generates errors, so just use these two suites for now
-packs = ["code-scanning", "security-extended"]
+# generate query-help fails for some queries in these suites. Faliures generate an error message.
+packs = ["code-scanning", "security-and-quality", "security-extended"]
 
 
 def prefix_repo_nwo(filename):

docs/language/query-help/conf.py

@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Learn CodeQL documentation build configuration file, created by
-# on Tuesday Nov 13 2018.
+# CodeQL query help configuration file
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
@@ -15,16 +14,6 @@
 # For details of all possible config values, 
 # see https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-#################################################################################
-#
-# Modified 22052019. 
-
-# The configuration values below are specific to the learning ql project
-# To amend html_theme_options, update version/release number, or add more sphinx extensions,
-# refer to  code/documentation/ql-documentation/global-sphinx-files/global-conf.py
-#
-##################################################################################
-
 # -- Project-specific configuration -----------------------------------
 
 import os
@@ -44,7 +33,6 @@ master_doc = 'index'
 project = u'CodeQL query help'
 
 # Add md parser to process query help markdown files 
-
 extensions =['recommonmark']
 
 source_suffix = {
@@ -82,4 +70,5 @@ source_suffix = {
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['toc-*']
+
+exclude_patterns = ['toc-*'] # ignore toc-<lang>.rst files as they are 'included' in index pages

docs/language/query-help/query-list.rst

@@ -1,7 +0,0 @@
-Code scanning query lists
-=========================
-
-.. csv-table:: 
-   :class: fullWidthTable
-   :widths: auto
-   :file: query-lists/query-list.csv

docs/language/query-help/readme.txt

@@ -0,0 +1,8 @@
+CodeQL query help Sphinx documentation
+--------------------------------------
+
+This project supplies the configuration and some boiler plate
+index files for the CodeQL query help documentation.
+
+The query help itself is automatically generated by the 
+"Generate CodeQL query help documentation using Sphinx" workflow.