improve docs

james · james · commit 4a9b61274ad0 · 2020-11-19T09:45:20.000Z
diff --git a/.github/workflows/generate-query-help-docs.yml b/.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:
diff --git a/docs/language/query-help-markdown.py b/docs/language/query-help-markdown.py
@@ -5,11 +5,24 @@
 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):
diff --git a/docs/language/query-help/conf.py b/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 @@
 project = u'CodeQL query help'
 
 # Add md parser to process query help markdown files 
-
 extensions =['recommonmark']
 
 source_suffix = {
@@ -82,4 +70,5 @@
 
 # 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
diff --git a/docs/language/query-help/query-list.rst b/docs/language/query-help/query-list.rst
diff --git a/docs/language/query-help/readme.txt b/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.

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-name: Generate CodeQL documentation using Sphinx`
	`1`	`+name: Generate CodeQL query help documentation using Sphinx`
`2`	`2`
`3`	`3`	`on:`
`4`	`4`	`push:`