codeql-info/ql/docs/language/learn-ql/build.latex/README.org

• Contents
• Building the documentation

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.

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