Short Exam

This example shows how to build a single-level multiple-choice quiz using the short.tex template with toplevel: true. When toplevel is set, the questions from the short-answer template become the document’s top-level enumerate items (numbered 1., 2., 3., …) rather than sub-items (a., b., c., …) nested inside an outer question block. All files for this example are in the examples/short_exam/ directory.

The working directory contains a configuration file and a question bank:

short_exam/
├── ShortExam.yaml        # pygacity configuration
└── science_mcq.yaml      # MCQ question bank (8 questions, 5 drawn per copy)

The Configuration File

document:
  preamble:
    pagestyle: ~
    font: |
      \setmainfont{Lato}
    commands:
      Universityname: University of Nowhere
      Departmentname: Mechanical Engineering
      Instructorname: Eustace T. Smartypants
      Instructoremail: ets@unow.edu
      Termcode: 202525
      Termname: Winter 2025-2026
      Coursename: BIO 5678 - Applied Pyrohydrodynamics
  structure:
    - pythontex:
        - setup
    - text: |
        \examheader{Quiz 1}{January 13, 2026}
        \noindent\textbf{Instructions:} This is a closed-book quiz.
    - source: short.tex
      config: science_mcq.yaml
      toplevel: true
    - pythontex:
        - teardown
build:
  seed: 42
  copies: 3
  job-name: Quiz1
  paths:
    build-dir: ./build

The short.tex block has two key attributes:

  • config points to the YAML question bank.

  • toplevel: true signals that the items emitted by short.tex should form the document’s top-level question list. This suppresses the nested enumerate that would appear when short.tex is used as a sub-question inside a compound exam.

Without toplevel: true, the same block used inside a compound exam would produce an outer question number (1.) wrapping the inner sub-items (a., b., c., …). With toplevel: true and no question_number, the items are rendered directly as 1., 2., 3., … at the document level.

The Question Bank

config:
  count: 5
  shuffle: true
  instructions: |
    \textbf{Multiple choice.}  Circle the letter of the best answer.
  type: multiple_choice
  shuffle_choices: true
content:
  - Q: What is the SI unit of electric current?
    choices:
      A: Volt
      B: Watt
      C: Ampere
      D: Ohm
    A: C
    text: The ampere (A) is the SI base unit of electric current.
  - Q: Which gas makes up the largest fraction of Earth's atmosphere?
    choices:
      A: Oxygen
      B: Argon
      C: Carbon dioxide
      D: Nitrogen
    A: D
    text: Nitrogen makes up approximately 78\% of Earth's atmosphere.
  - Q: What is the speed of light in a vacuum?
    choices:
      A: \(3.0 \times 10^6\) m/s
      B: \(3.0 \times 10^8\) m/s
      C: \(3.0 \times 10^{10}\) m/s
      D: \(3.0 \times 10^{12}\) m/s
    A: B
    text: The speed of light in a vacuum is approximately \(3.0 \times 10^8\) m/s.
  - Q: Which of the following is a vector quantity?
    choices:
      A: Mass
      B: Temperature
      C: Speed
      D: Velocity
    A: D
    text: Velocity is a vector quantity because it has both magnitude and direction. Speed is a scalar.
  - Q: What is the chemical symbol for gold?
    choices:
      A: Go
      B: Gd
      C: Au
      D: Ag
    A: C
    text: Gold's chemical symbol Au comes from the Latin word \textit{aurum}.
  - Q: Which law states that the pressure of a fixed amount of gas is inversely proportional to its volume at constant temperature?
    choices:
      A: Charles's Law
      B: Avogadro's Law
      C: Boyle's Law
      D: Gay-Lussac's Law
    A: C
    text: Boyle's Law states that \(P \propto 1/V\) at constant temperature.
  - Q: How many protons does a carbon atom have?
    choices:
      A: 4
      B: 6
      C: 8
      D: 12
    A: B
    text: Carbon has atomic number 6, meaning it has 6 protons in its nucleus.
  - Q: What is the unit of frequency?
    choices:
      A: Joule
      B: Newton
      C: Pascal
      D: Hertz
    A: D
    text: Frequency is measured in hertz (Hz), where 1 Hz = 1 cycle per second.

The config section draws 5 questions at random from the 8 in the bank and shuffles the choice order for each question independently. The content list supplies the full question pool; pygacity selects and shuffles at build time using the per-copy random seed.

Building the Document

From inside the short_exam/ directory, run:

pygacity build ShortExam.yaml

Output

After a successful build, the build/ directory contains one student PDF and one solutions PDF per copy (three copies in this example), plus zipped build artifacts.

Because questions are drawn and shuffled independently for each copy, two student PDFs will show different question sets and different choice orderings:

Short exam, copy 1

Copy 1
Short exam, copy 2

Copy 2

The solutions PDF for copy 1 shows the correct answer highlighted for each question:

Short exam solutions, copy 1