Merge pull request #4997 from github/shati-patel/cwe-coverage-docs

Docs: Add outline for CWE coverage page

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

@@ -50,7 +50,7 @@ jobs:
       uses: ammaraskar/sphinx-action@8b4f60114d7fd1faeba1a712269168508d4750d2 # v0.4
       with:
         docs-folder: "query-help/"
-        pre-build-command: "python -m pip install --upgrade recommonmark"
+        pre-build-command: "python -m pip install --upgrade recommonmark && python -m pip install --upgrade sphinx-markdown-tables"
         build-command: "sphinx-build -b dirhtml . _build" 
     - name: Upload HTML artifacts
       uses: actions/upload-artifact@v2

docs/codeql/query-help/codeql-cwe-coverage.md

@@ -0,0 +1,25 @@
+# CodeQL CWE coverage
+
+An overview of the coverage of MITRE's Common Weakness Enumeration (CWE) for the latest release of CodeQL.
+
+## About CWEs
+
+The CWE categorization contains several types of entity, collectively known as CWEs. The CWEs that we consider in this report are only those of the types:
+
+- Weakness Class
+- Weakness Base
+- Weakness Variant
+- Compound Element
+
+Other types of CWE do not correspond directly to weaknesses, so are omitted.
+
+The CWE categorization includes relationships between entities, in particular a parent-child relationship.
+These relationships are associated with Views (another kind of CWE entity). For the purposes of coverage claims, we use the "[Research View](https://cwe.mitre.org/data/definitions/1000.html)."
+
+Every security query is associated with one or more CWEs, which are the most precise CWEs that are covered by that query.
+Overall coverage is claimed for the most-precise CWEs, as well as for any of their ancestors in the View.
+
+## Overview
+
+<!-- autogenerated CWE coverage table will be added below -->
+

docs/codeql/query-help/conf.py

@@ -23,7 +23,10 @@ master_doc = 'index'
 project = u'CodeQL query help'
 
 # Add md parser to process query help markdown files 
-extensions =['recommonmark']
+extensions = [
+    'recommonmark',
+    'sphinx_markdown_tables',
+]
 
 source_suffix = {
     '.rst': 'restructuredtext',

docs/codeql/query-help/index.rst

@@ -20,6 +20,9 @@ View the query help for the queries included in the ``code-scanning``, ``securit
    - 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.
 
+
+For a full list of the CWEs covered by these queries, see ":doc:`CodeQL CWE coverage <codeql-cwe-coverage>`." 
+
 .. toctree::
    :hidden:
    :titlesonly:
@@ -30,4 +33,5 @@ View the query help for the queries included in the ``code-scanning``, ``securit
    java
    javascript
    python
+   codeql-cwe-coverage