Add support for externalizing tikz images.

This commit will cause all the tikz images to be generated first in the
tikz-cache folder before being included in the main PDF file. There are
several issues that need to be resolved for this to work:
- Whatever command is being used to compile the document (e.g. `latexmk`
or `pdflatex` needs to have the `-shell-escape` flag added.
- The tikz-cache folder is not auto-generated, so it is being tracked in
version control to avoid users cloning the repo and seeing mysterious
error messages when compiling. No cached tikz files should be added to
this directory.
- The \newenvironment command used in our custom circuit and plot
environments does not play well with the externalizing library. These
were modified to use the environ library which solves the problem as
described [here](https://tex.stackexchange.com/a/15614)
- This caching significantly improves the compile time when figures are
already cached, but the first compile takes much longer since the image
compilation is single-threaded. However, it is possible to use
tikzexternalize in `list and make` mode which allows you to use `make
-j` to compile all the images using multiple threads. This requires
running the pdflatex commands manually without some more complex
configuration of a latexmkrc file. Only attempt this if you know what
you are doing. Otherwise, just wait a couple minutes for the
compilation.

.github/workflows/latex-pdf.yml

@@ -13,6 +13,7 @@ jobs:
               uses: xu-cheng/latex-action@v2
               with:
                   root_file: main.tex
+                  latexmk_shell_escape: true
 
             - name: Upload Artifact
               uses: actions/upload-artifact@v2

.github/workflows/publish-latest.yml

@@ -19,6 +19,7 @@ jobs:
         with:
           working_directory: 'taoe3'
           root_file: 'main.tex'
+          latexmk_shell_escape: true
 
       - name: Checkout gh_pages branch
         uses: actions/checkout@v2

.gitignore

@@ -38,3 +38,7 @@
 # latexrun
 latex.out/
 
+## Tikz externalize files
+*.makefile
+*.figlist
+*.auxlock

taoesolutions.sty

@@ -2,6 +2,7 @@
 
 \usepackage{circuitikz}
 \usepackage{pgfplots}
+\usepackage{environ}
 \usepackage{amsmath}
 \usepackage{cancel}
 \usepackage{enumitem}
@@ -13,6 +14,10 @@
 ]{geometry}
 \usepackage[toc]{multitoc}
 
+\usetikzlibrary{external}
+\tikzexternalize[prefix=tikz-cache/]
+% \tikzexternalize[prefix=tikz-cache/, mode=list and make]
+
 % Remove the "Chapter" label on each chapter
 \usepackage{titlesec}
 \titleformat{\chapter}[display]
@@ -43,39 +48,63 @@
 \newcommand{\ave}{\ensuremath{\text{ave}}} % average
 \newcommand{\eq}{\ensuremath{\text{eq}}} % equivalent 
 
-\newenvironment{circuit}[2]% param1=label, param2=caption
-    {
-        \begin{figure}[H]
+\NewEnviron{circuit}[2]{%
+    \begin{figure}[H]
         \caption{#2}
         \label{#1}
-
-        \begin{center} 
-        % \centering
-        \begin{circuitikz}[american]\draw
-    }
-    {
+        \begin{center}
+        \begin{tikzpicture}[american]\draw
+            \BODY
         ;
-        \end{circuitikz}
+        \end{tikzpicture}
         \end{center}
-        \end{figure}
-    }
+        \end{figure}}
+
+% \newenvironment{circuit}[2]% param1=label, param2=caption
+%     {
+%         \begin{figure}[H]
+%         \caption{#2}
+%         \label{#1}
+
+%         \begin{center} 
+%         % \centering
+%         \begin{tikzpicture}[american]\draw
+%     }
+%     {
+%         ;
+%         \end{tikzpicture}
+%         \end{center}
+%         \end{figure}
+%     }
 
-\newenvironment{plot}[2]% param1=label, param2=caption
-    {
-        \begin{figure}[H]
+\NewEnviron{plot}[2]{%
+    \begin{figure}[H]
         \caption{#2}
         \label{#1}
-
-        \begin{center} 
-        % \centering
+        \begin{center}
         \begin{tikzpicture}[scale=0.8, samples=200]\draw
-    }
-    {
+            \BODY
         ;
         \end{tikzpicture}
         \end{center}
-        \end{figure}
-    }
+        \end{figure}}
+
+% \newenvironment{plot}[2]% param1=label, param2=caption
+%     {
+%         \begin{figure}[H]
+%         \caption{#2}
+%         \label{#1}
+
+%         \begin{center} 
+%         % \centering
+%         \begin{tikzpicture}[scale=0.8, samples=200]\draw
+%     }
+%     {
+%         ;
+%         \end{tikzpicture}
+%         \end{center}
+%         \end{figure}
+%     }
 % Set first level of list to (a) format
 \setlist[enumerate,1]{label=(\alph*)}
 

tikz-cache/.gitignore

@@ -0,0 +1,6 @@
+# This tikz-cache folder is here to cache the tikz images.
+# It is needed by the \tikzpackage{external} library.
+# This folder is not automatically generated, so it's tracked in version control
+# to prevent new users from seeing cryptic compile errors.
+*
+!.gitignore