Document Compilation

Once a configuration file has been created describing the document to be built and how to build it, the document can be compiled using the pygacity build command. This command reads the configuration file, generates the necessary LaTeX code, and compiles the document. During this process, if any python code is included in the document using pythontex, it will be executed and the results will be incorporated into the final document.

For a configuration file my_config.yaml, the command to build the document is:

pygacity build my_config.yaml

This will produce the final document in PDF format in the output directory specified in the configuration file.

--bundle-size and --two-sided

pygacity build also accepts two options for generating print-ready bundle PDFs that combine multiple exam copies into a single file:

pygacity build my_config.yaml --bundle-size 15 --two-sided

--bundle-size N (default: 10) groups the generated student exam PDFs into bundles of at most N copies and writes one bundle PDF per group alongside the individual exam files. Pass --bundle-size 0 to disable bundling entirely.

--two-sided (default: off) pads each exam to an even page count by appending a blank page whenever an exam has an odd number of pages. This guarantees that the first page of every exam in a bundle falls on a right-hand sheet when the bundle is printed double-sided. Use --no-two-sided to explicitly disable it.

By default, if an output directory is not specified, the document will be generated in a subdictory named build/ in the current working directory. By default, pygacity generates several outputs in the build directory. For example, if job-name is set to Assignment, the following files will be generated:

build/
├── Assignment.pdf        # Final document
├── Assignment_soln.pdf   # Final document with solutions
├── buildfiles.zip        # Files created by the build process
├── .cache/               # Cache directory (may be empty)
│   └── ...               # Cached files (if any)
├── solnbuildfiles.zip    # Files created by the solution build process
└── tex_artifacts.zip     # Any LaTeX code files generated by pygacity

When building multiple versions of a document (i.e., when copies is greater than 1), each version will be generated with a unique serial number appended to the job name. For example, if job-name is set to ExamI and copies is set to 3 (and seed is set to 12345), the following files will be generated:

build
├── answerset_buildfiles.zip
├── answerset.pdf
├── buildfiles.zip
├── .cache
│   ├── answers-11364882.pkl
│   ├── answers-50082762.pkl
│   └── answers-65917772.pkl
├── ExamI-11364882.pdf
├── ExamI-11364882_soln.pdf
├── ExamI-50082762.pdf
├── ExamI-50082762_soln.pdf
├── ExamI-65917772.pdf
├── ExamI-65917772_soln.pdf
├── ExamI-bundle-1.pdf
├── solnbuildfiles.zip
└── tex_artifacts.zip

Note the three unique exam versions and their accompanying solution documents, each with a unique serial number. Note also answerset.pdf, which contains all of the answers for all versions of the exam in one document for easy reference, and ExamI-bundle-1.pdf, which combines all three student exams into a single print-ready PDF (all three fit in one bundle with the default bundle size of 10). The cached answer files in the .cache/ directory store the generated answers for each serial in case a new answer set needs to be regenerated.

When build.serial-hex is true, serial numbers appear as zero-padded hexadecimal strings in all filenames (e.g. ExamI-00ad6a12.pdf instead of ExamI-11364882.pdf). The width of the hex string is controlled by build.serial-hex-digits (default: 8).