This repository's primary purpose is to make document generation easier for course staff.
created by Alvin Wan and Sinho Chewi
Clone the repository and change into the directory.
git clone https://github.com/alvinwan/materials.git
cd materials
Check that you have Latex installed. Then, install the necessary Python dependencies. (Optionally, install in a virtual environment instead of the following.)
pip install -r requirements.txt
If you are only using this repository to review or create documents from the command line, installation is complete. If you would like to generate image files to post on Piazza, you will need NodeJS and ImageMagick installed (for now).
On Mac, Homebrew is the recommended package manager:
brew install imagemagick npm nodejs
installs ImageMagick, NodeJS and its package managernpm
.
Install the Node packages required for the Piazza script.
npm install package.json
Installation complete. See "How to Use" to get started.
All commands are available via make
. If for some reason, make
is not installed on your OS, check the Makefile
for the bash commands. For rendering assignments, you will not need the virtual environment. Only specific make commands require it, and when required, instructions below will specify how to activate the virtual environment.
For code, just add one solution file. This file must have the same name as your original tex
file. For example, if the original file is extended-gcd.tex
, the file must be named extended-gcd.py
. Delimit all question solutions using %%% start [name] %%%
and %%% end [name] %%%
, where [name]
is any string, without punctuation. For example, see this solution file. There are two solutions sections, one named a
and the other named b
.
def extended_gcd(x, y):
print('x:', x, 'y:', y)
if y == 0:
### start a ###
return (x, 1, 0)
### end a ###
else:
### start b ###
d, a, b = extended_gcd(y, x % y)
print('d:', d, 'a:', a, 'b:', b)
return (d, b, a - (x // y)*b)
### end b ###
In your .tex
file, insert the relevant code in your solutions, using the %%% insert [name] %%%
syntax. Here, we insert both solution parts a
and b
. These names have no significance and can be arbitrary.
\Question{Extended GCD}
\begin{Parts}
\Part Program the base case.
\begin{solution}
\begin{lstlisting}
%%% insert a %%%
\end{lstlisting}
\end{solution}
\Part Program the recursive case.
\begin{solution}
\begin{lstlisting}
%%% insert b %%%%
\end{lstlisting}
\end{solution}
\end{Parts}
The script will automatically:
- Insert relevant code sections into your solutions PDF.
- Generate a starter
.py
file in the document's respective output directory. - Copy solution
.py
into the document's respective output directory.
We now support a workflow which produces the .tex
files from templates. The templates are located at src/[category]/template.tex
and src/[category]/template-sol.tex
. In order to make the actual documents, the only documents you need to edit are: a base .base.tex
file containing the input problems, and the .tex
files for the problems themselves.
Here, we will create a new document of the form [category][num]
. This may be a discussion or homework; for simplicity, let us consider a document dis01a
.
First, navigate to src/dis/
, and make a file called dis01a.base.tex
.
cd src/dis
touch dis01a.base.tex
Open up dis01a.base.tex
using a text editor of your choice. Here is an example:
\input{modulararithmetic/text/introduction.tex}
\input{modulararithmetic/divisible-or-not.tex}
This file should only contain a list of \input{...}
, each on its own line, referencing a problem or a text blurb. Browse through problems in src/problems/
, and add problems above.
Note: An old version of this repository split files into
folder/question.tex
andfolder/question.tex
. Simply merge the two.
The file starts with the command \Question
. You are free to include whatever you want afterwards, and the solution should be wrapped in the solution
environment. Example:
\Question{Compute This}
Suppose you had a program...
\begin{solution}
The program can indeed be computed by...
\end{solution}
First, navigate to the root directory of this repo. In other words pwd
should end with /materials
.
Then, to render an assignment, use make [category] n=[number]
.
The following are valid categories:
dis
hw
For example, to make Discussion 1a, use
make dis n=01a
This will create two PDF files:
rendered/dis01a/dis01a.pdf
rendered/dis01a/dis01a-sol.pdf
What's going on when you run the command?
- First, the Python script
generate.py
is run to generate the.tex
files from the base tex file, along with the embedded template files (files matchingtemplate-*.tex
). (After rendering, you should find the generated.tex
files insrc/[category]
. - Then, the generated
.tex
files are compiled into.pdf
files, and dumped into therendered
directory.
After running make hw n=[number]
as above, the command make img n=[number]
will generate PNG image files, also in the rendered
directory. To use this feature, you must have ImageMagick installed (see the requirements above).
Before using this utility, make sure to create config.json
. We have provided a sample for you to fill in. You may duplicate the sample to get started.
cp sample_config.json config.json
We have provided a Piazza Course id, created for anyone to test on. You must fill in username
and password
with valid Piazza credentials.
After generating images per instructions in the previous section and setting up your configuration file, the command make piazza n=[number]
will post all images on Piazza.
Setup your virtual environment. The following will create a new environment called course
.
conda create -n course python=3.5
Activate your virtual environment, and install all dependencies from requirements.txt
.
source activate course
pip install -r requirements.txt
At this point, you may exit your virtual environment
source deactivate