‎

1. Contents
2. Building the documentation

1. Contents

This directory has two PDF files pre-built from the codeql documentation tree.

This is the same content as https://codeql.github.com/docs/codeql-language-guides/, but built from the source's master branch as of [2021-07-27 Tue], resulting in a slightly different structure.

The files:

./LearningCodeQL-768e5190a1.pdf uses the Bitstream Charter font instead of Times Roman
./LearningCodeQL-768e5190a1-14pt.pdf also uses the Bitstream Charter font instead of Times Roman, and additionally uses a 14pt font size for smaller devices like ipads.
./QLlanguagereference-14pt.pdf also uses the Bitstream Charter font instead of Times Roman, and additionally uses a 14pt font size for smaller devices like ipads.

2. Building the documentation

Here is a very short summary of the build steps for the files.

# Clone the codeql library
mkdir -p ~/local/0ec126bc
cd ~/local/0ec126bc
git clone https://github.com/github/codeql ql

# Install prerequisites
# Igore the docs, try python 3 and new version of docutils.
pip install docutils
pip install -U sphinx

# Patch
git patch << EOF
diff --git a/docs/codeql/conf.py b/docs/codeql/conf.py
index da8b911402..3ff626bceb 100644
--- a/docs/codeql/conf.py
+++ b/docs/codeql/conf.py
@@ -51,8 +51,8 @@ import sys

 def setup(sphinx):
     sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) 
-    from qllexer import QLLexer
-    sphinx.add_lexer("ql", QLLexer())
+    # from qllexer import QLLexer
+    # sphinx.add_lexer("ql", QLLexer())

 # The version of CodeQL for the current release you're documenting, acts as replacement for
 # |version| and |release|. Not currently used.
diff --git a/docs/codeql/ql-training/conf.py b/docs/codeql/ql-training/conf.py
index 1c36b806de..a9ed0d0429 100644
--- a/docs/codeql/ql-training/conf.py
+++ b/docs/codeql/ql-training/conf.py
@@ -48,8 +48,8 @@ import os

 def setup(sphinx):
     sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.path.pardir))
-    from qllexer import QLLexer
-    sphinx.add_lexer("ql", QLLexer())
+    # from qllexer import QLLexer
+    # sphinx.add_lexer("ql", QLLexer())

 # Set QL as the default language for highlighting code. Set to none to disable 
 # syntax highlighting. If omitted or left blank, it defaults to Python 3. 
@@ -122,4 +122,4 @@ html_theme_options = {'font_size': '16px',
 # Exclude the slide snippets from the build
 exclude_patterns = ['slide-snippets']
EOF

#* Build the html documentation 
cd ~/local/0ec126bc/ql/docs/codeql/
# See /Users/hohn/local/0ec126bc/ql/docs/codeql/README.rst for details. 
sphinx-build -b html . build.html

# View main index page
open build.html/codeql-overview/index.html

# Detail page source
em ./writing-codeql-queries/creating-path-queries.rst

# View one of the index pages
open build.html/codeql-language-guides/codeql-library-for-javascript.html

# Find classic datflow version (class based)
git log -6 ./writing-codeql-queries/debugging-data-flow-queries-using-partial-flow.rst |cat
# commit 2947f176ef90570f854e18acee024a9dff9b8bed
# Author: Anders Schack-Mulligen <aschackmull@github.com>
# Date:   Thu Jul 13 09:21:12 2023 +0200
#     Docs: Update data flow documentation to the new API.

# one prior:
git stash save custom-conf
git checkout f3f2c3183
git stash apply stash@{0}

# and re-build
sphinx-build -b html . build.html

# Keep a copy
cd ~/local/codeql-info/ql/docs/language/learn-ql/
cp -r ~/local/0ec126bc/ql/docs/codeql/build.html build.html-$(git rev-parse --short HEAD)

# View main index page
open ~/local/codeql-info/ql/docs/language/learn-ql/build.html-$(git rev-parse --short HEAD)/codeql-overview/index.html

#* Build the PDF version
cd ~/local/0ec126bc/ql/docs/codeql/
sphinx-build -b latex . build.latex
cd build.latex/

# fails:
# make all

pdflatex codeqldocumentation.tex

open codeqldocumentation.pdf

# Keep a copy
cd ~/local/codeql-info/ql/docs/language/learn-ql/
dest=$HOME/local/codeql-info/ql/docs/language/learn-ql/build.latex-$(git rev-parse --short HEAD)

mkdir $dest
cd $dest
cp ~/local/0ec126bc/ql/docs/codeql/build.latex/codeqldocumentation.pdf .


# # Optional:
# # Customize the latex source
# # More depth for table of contents
# perl -i -p -e 's/\\setcounter\{tocdepth\}\{0\}/\\setcounter{tocdepth}{3}/g;' LearningCodeQL.tex
# # Change the font:
# # comment
# #     % \usepackage{times}
# # and use 
# #     \usepackage[bitstream-charter]{mathdesign}
# #     \renewcommand{\baselinestretch}{1.1}
# # instead.

# # For the 14pt version, add:
# #     \usepackage[fontsize=14]{scrextend}

# # Run xelatex twice
# xelatex -shell-escape  -interaction=nonstopmode LearningCodeQL.tex
# xelatex -shell-escape  -interaction=nonstopmode LearningCodeQL.tex

# open LearningCodeQL.pdf

For the QL language reference:

# Build the PDF version
cd ~/local/vmsync/ql/docs/language/ql-handbook
sphinx-build -b latex . build.latex

# Customize the latex source
cd ~/local/vmsync/ql/docs/language/ql-handbook/build.latex/

# More depth for table of contents: change to 
# \setcounter{tocdepth}{3}
# 
# Change the font for the 14pt version:
# comment
#     % \usepackage{times}
# and use 
#     \usepackage[bitstream-charter]{mathdesign}
#     \renewcommand{\baselinestretch}{1.1}
# instead.
# 
# For the 14pt version, add:
#     \usepackage[fontsize=14]{scrextend}

# Run xelatex twice
xelatex -shell-escape  -interaction=nonstopmode QLlanguagereference.tex
xelatex -shell-escape  -interaction=nonstopmode QLlanguagereference.tex

open QLlanguagereference.pdf

Table of Contents

1. Contents

2. Building the documentation