Course Documents

This is a directory structure and document generator for the various documents one needs to create while teaching a course (e.g. lecture notes, slides, worksheets, homework solutions, quizzes, ...). This is originally designed for courses in quantitative fields, but could also be useful in other fields.

Note I use this myself for multiple courses, and it works well for me, but this has not been widely tested on a large scale.

• Motivation
• Features
• Folder Structure
• Set-Up
• Usage
  • Scripts
    • scripts/create_document.py
    • scripts/create_problems.py
  • Importing problems into documents
  • Autogeneration
• Tips

Motivation

If you've ever taught a quantitative course and created documents for it with $\LaTeX$, you may have an ad hoc list of custom macros and package imports that you haphazardly copy and paste into the top of every new document you make for the course (worksheet, test, etc.). The goal of this project is to ease the burden of the logistics of creating course documents with $\LaTeX$ for instructors, so they can focus on the most important part: the content.

Features

This repository is a template repository, designed to be cloned and used for creating documents for an individual course. Besides the obvious benefit that version controlling course documents provides (tracking changes over semesters, recreating a document exactly how it looked when it was first handed out, etc.), this project also:

• provides a framework for storing the statements and/or solutions for problems, as well as the original source, from the various places one draws problems from when creating course documents (e.g. textbooks, colleagues, yourself), which can then be easily imported into documents of any type with a single command
• uses templates and package imports for creating documents of each type (quiz, lecture-notes, worksheet, etc.) to make style and notation automatically consistent
• allows for automatic generation of "extra versions" of given documents, e.g. creating a quiz and quiz-solutions file alongside each other
• provides a means to autogenerate documents like homework solutions using the files stored in the problems directory

Folder Structure

Since this is a template repository, before describing the setup, it will be helpful to understand the folder structure of the repo. The top-level directory has the following subfolders (or will after setup):

• documents: the folder which will hold all the actual created documents for use in the course (e.g. notes, worksheets, quizzes, tests, etc.)
• includes: LaTeX files which will be included in the preamble of documents, providing consistency of notation, and functionality for including content of problems
• problems: files related to problems from different sources (e.g. textbooks, colleagues, yourself, online resources).
• scripts: python scripts and accompanying yaml files for creating documents and problems. You'll run these scripts frequently as you create documents.
• templates: templates of course document LaTeX files which are used by the scripts for creating individual documents.

Warning At present, pdf files will be ignored by git, since the pdfs generated by TeX are reproducible. This can present a problem if trying to include pdf graphics in the repository for insertion into a TeX file. For that reason, any pdf files in folders named img (or subdirectories thereof) will not be ignored.

Set-Up

1. git clone the repository and don't set this repo as the upstream.

2. (Optional) This repo is currently using the custom $\LaTeX$ document classes and packages in my personal texmf repository. You can either make these accessible in the $\TeX$ environment on your machine, or you'll need to edit the templates later to use different document classes later.

3. Edit scripts/config.yaml for your needs in this course.

   • Edit/add problem sources. Problem sources could include textbooks, colleagues, etc. IMPORTANT: Use only alphabetical characters for names (maybe use roman numerals for edition numbers of textbooks). These should all be uniquely named, so change the name generic textbook source currently present for the name of the textbook for the course, e.g. stewartviii might be the name for the eighth edition of Stewart's Calclulus book. Don't worry about getting all possible problem sources right away. This is easily added to later.
     • standard_tex_files is an array of files to be created when a problem is created. The files statement and solution should be considered the default. Leave this as is if unsure. Another file you might want to include by default could include hint.
     • directory_levels indicates for this problem source how deep the directory structure will go for top-level problems. E.g. if textbook problems will be organized by chapter/section/problem_number, then set this option to 3. Problems may have subparts; this number is indicating how deep in the directory structure problems will begin.
   • (Optional) Edit/add document types for the course.
     • default_directory is the subdirectory of the documents folder that a new document of that type will be placed when creating documents, unless otherwise specified. (Note: any strings between %( and )s are parameters that will be specified at the time of document creation.)
     • default_filename is the format of the name for a document of that type, unless otherwise specified. (Note: any strings between %( and )s are parameters that will be specified at the time of document creation.)
     • includes are the files from the directory of includes that will be imported in order at the top of tex files of the given document type. The global and probimport should essentially be included in any document type. The course-info include is for use with the LaTeX document classes in my personal texmf repository (Note: For includes for clicker-questions, the include clicker-questions must be included before course-info.) If you're not sure if you need/want to change these yet, you can come back to it later.
     • extra_versions is for automatically creating .tex file(s) for a different version of the document type. The keys are the names of the other versions, and the values are dictionaries with keys options and class. The latter should correspond to the document class in the template for the document type (see templates below). The former is a comma-separated list of options to be added to the LaTeX document class for the extra version. For instance, the exam class accepts an option answers to print the document with solutions visible. By default, the quiz, worksheet, and test document types have an extra version for solutions enabled.
     • autogenerated is an optional property for document types that can be automatically generated from a list of problems to include. The value of this option is the JSON file to store which problem files to pull. By default, hw-solutions is set to be autogenerated as an example.

4. Set up the includes directory

   • (Optional) If using my personal texmf repository, edit includes/course-info.tex with your course's information.
   • Edit includes/global.tex to add any packages or macros you will want to be accessible in all possible documents. This will likely be added to as the course progresses and more macros are needed for more concepts.
   • Edit includes/paper.tex to add any packages or macros you want accessible in any paper (read non-slide) document types. Perhaps you want to set a font.
   • Edit includes/slides.tex to set any packages you want to import in slide document types.
   • (Optional) Now that you have a sense of what the includes are for, go back and make sure each document type in the config file has the right includes set for it. If there's extra functionality you need, feel free to create a new include and set some document type(s) to use it.

5. (Optional) Edit the files in templates to suit your needs. Besides the all-problems.tex template, each corresponds by name to a document type in the config file. These will be loaded by the script creating the documents. At present, they use some of the custom document classes from my personal texmf repository. If you are using those, you don't have to change anything here. If you are not using the given document classes, you'll need to edit/create the template yourself. Each should have \newcommand{\rootdir}{ROOTDIR} and INCLUDES somewhere in the preamble, as well as the word TITLE somewhere, even if not in \title.

Usage

Scripts

After setup, there are two main scripts one will call.

scripts/create_document.py

Used for actually creating a document. The arguments of the script are:

• document_type: The first positional argument is for specifying the type of document to create. Valid options are the keys of document_types in scripts/config.yaml. By default, these are hw-solutions, quiz, lecture-notes, worksheet, test, slides, and clicker-questions.
• title: The second positional argument is the title of the document that will be used as the title of the LaTeX document (and potentially in the file or directory name; see flag -s).
• -d DIRECTORY (optional): the relative directory in the documents folder to write the file, a default is set in the scripts/config.yaml file by document type.
• -f FILENAME (optional): the name of the created file; a default is set in the scripts/config.yaml file by document type.
• -s OLD_STRING NEW_STRING (optional): If the default filename or given filename has any parameters that should be replaced, e.g. if the filename is %(section)s-notes, you would use the flag -s section 3.4 to replace "%(section)s" in the filename with "3.4". This option can be used for multiple parameters.

If you forget these options, just use the -h or --help flag.

If a document type is set to be autogenerated, the document file created will be fully populated and ready for compiling (see Autogeneration). Otherwise, a bare version has been created for you to edit. It will be in a state with all the relevant packages and macros loaded, so that you can focus on the content instead of the LaTeX details. Once you're satisfied, compile the .tex source code to get your document.

scripts/create_problems.py

Used for actually creating problem files. The arguments of the script are:

• source: The only positional argument is for specifying the problem source of the problems being created. Valid options are the keys of problem_sources in scripts/config.yaml.
• -p PROBLEM | -s STRING | -f FILE: exactly one of these is required to specify which problems to create files for in the directory problems/<source>
  • -p PROBLEM: the path to a single problem, e.g. for problem 34 in section 12.5, you might use -p "12/5/34"
  • -s STRING: a json string of nested objects (dicts) and strings or lists to allow for simultaneous creation of multiple problems. The string represents the directory structure to get to the desired problems, e.g. for problems 12.3.2, 12.3.4, and 12.5.3, this would be -s '{"12": {"3": ["2", "4"]}, {"5": ["3"]}}'
  • -f FILE: a yaml or json file (with similar structur to -s) for creating multiple files at once.

If you forget these options, just use the -h or --help flag.

Note Each file created with this script is populated with the text "(NOT WRITTEN)", rather than being an empty file. This is so that after compiling the parent document, synctex can be used to quickly open the relevant problem files for editing.

Note For autogenerated files, creation of the problem files themselves will be automated, so you don't need to call this function first.

Importing problems into documents

The include probimport.tex provides LaTeX commands for importing the problems created above into a document. These are:

• pimport which take two arguments: the path (within problems) to the problem directory, and the name of the file to import (e.g. "solution" or "statement")
• pquestion which takes one required argument, the path (within problems) to the problem directory, and an optional argument for the point value. This command is like pimport{<path>}{statement} preceded by the \question macro, for use in the exam document class.
• pquestionsol which takes 2 required arguments, the path to the problem, and the space to leave for the solution. This is like the pquestion environment, but leaves space and so is useful for autogenerating a solutions version of a document, because the solution will be visible if the option answers is passed to the exam class.
• ppart, ppartsol, psubpart, and psubpartsol which are similar to pquestion and pquestionsol and need no further explanation
• pitem, which is like the above, but for \item instead of \question

For example, to include question 12.5.3 from source 'textbook' in a worksheet document and leave 3 inches for the solution, I would write \pquestionsol{textbook/12/5/3}{3in}.

Autogeneration

By default, the hw-solutions document type is set to be autogenerated. For this to happen automatically,

1. the string PROBLEMS must appear in the template of the document type (templates/hw-solutions.tex)
2. there must be a file in the includes folder with the name of the document type, specifying commands for every source that might show up in the document type
3. there must be another yaml file in the scripts folder for setting which problems go with which document of the given type (in the example, this is homework_problems.yaml)
4. in the scripts/config.yaml file, the document type must have the autogenerated field set to the name of the yaml file in the previous step

With this setup, when a hw-solutions document type is created, the program looks for the provided title in homework_problems.yaml, and will fill the PROBLEMS portion of the template with the necessary calls of commands in the custom include file mentioned above.

Tips

1. During a semester that you're teaching the course, use the main branch for the course's current documents and have a long-running parallel branch of updates to make for the next time you run the course (e.g. f22edits). If you notice a mistake to fix, or a change you'd like to make in a future semester, and it's too late for that change this semester, merge the f22edits branch with main and add a commit to the f22edits with the desired change.
2. At the end of each semester, add a tag to make it easy to look back at the versions of documents from previous semesters.
3. The all-problems.tex template and make_all_problems.py script are for use in creating a single document with all the input files in the problems folder. This can be helpful for browsing the problems in the repo.
4. To ensure your most recent versions of your documents are always available to you (and possibly your students), you can use CI/CD to compile all the .tex files in the documents folder and sync them to a folder in a cloud storage service. I've set this up with Gitlab runners with great success.