# Getting started

This guide starts with a YAML question bank and ends with the QTI ZIP file that Canvas receives.
You do not need to understand Python code, XML, or the QTI file format.

## 1. Install Python

QuestionBankToolkit requires Python 3.14 or newer.
Download a current Python release from [python.org](https://www.python.org/downloads/) or use a trusted package manager supplied by your operating system.

Open Terminal on macOS or Linux, or PowerShell on Windows, and check the installed version.

```text
python --version
```

If that command does not find the intended interpreter on macOS or Linux, try `python3.14 --version`.
On Windows, the Python install manager also provides `py -3.14 --version`.

## 2. Install QuestionBankToolkit

Create an isolated virtual environment so the toolkit and its dependencies do not change other Python applications.

On macOS or Linux, run:

```bash
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install QuestionBankToolkit
```

On Windows PowerShell, run:

```powershell
py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install QuestionBankToolkit
```

The terminal prompt usually displays `(.venv)` while the environment is active.
Verify the command installation before writing a bank.

```text
coursebanks --help
```

Return to the directory containing the environment and activate it before later sessions.
Installing from a Git checkout and installing development tools are optional contributor workflows described in [development.md](development.md).

## 3. Create a YAML bank

Copy the complete bank below into a UTF-8 text file named `questions.yaml`.
It is also available as [the checked-in sample](https://codeberg.org/ddmarshall/QuestionBankToolkit/src/branch/main/examples/sample_course/questions.yaml).

```yaml
schema_version: 1
course: COURSE123
bank_id: Module1_Conceptual
title: COURSE123 Module 1 Conceptual Questions
default_shuffle_choices: true
questions:
  - id: M1C01
    title: Interpreting a reference scale
    area: Mathematical foundations
    topic: Nondimensional variables
    difficulty: Basic
    assessments: []
    minutes: 2
    points: 2
    format: plain
    stem: If a dimensional quantity is divided by its own reference scale, what is the result?
    choices:
      A: A dimensionless quantity.
      B: A dimensional quantity with squared units.
      C: An identically zero quantity.
      D: A quantity that cannot be compared between experiments.
    answer: A
    explanation: The units cancel when a quantity is divided by a reference scale with the same units.
```

YAML uses spaces and indentation to show structure.
Keep every question two spaces beneath `questions:`, its fields four spaces beneath the dash, and each choice six spaces beneath `choices:`.
Do not use tab characters.

The top-level `course`, `bank_id`, and `title` identify the bank and its generated files.
Each `id` must be unique and stable because QTI, reports, imports, and usage history use it to identify the question.
The `area`, `topic`, `difficulty`, and `minutes` fields help instructors review and select questions; Canvas grading uses `points`.
An empty `assessments: []` list allows the question to be used for any assessment.
Use a list such as `assessments: ["Quiz 1", "Final"]` to restrict optional selection workflows.

The keys below `choices:` are answer labels.
The `answer` value must exactly match one choice key, including capitalization.
The `explanation` becomes general feedback in the generated QTI package.

Quote text when YAML punctuation could change its meaning.
For example, write `title: "Week 1: Forces"`, `topic: "#hashtags"`, and `assessments: ["1"]`.
Do not quote `points`, `minutes`, `true`, or `false`, because those fields require YAML numbers or booleans rather than text.

Use YAML's folded block style for a long paragraph.

```yaml
stem: >-
  A long question can continue on additional indented lines.
  YAML folds these lines into one paragraph.
```

Use the literal block style when line breaks must remain part of authored HTML or text.

```yaml
explanation: |-
  First line of feedback.
  Second line of feedback.
```

See [the YAML schema](schema.md) for every field, valid value, default, and identifier rule.

## 4. Validate before building

Run validation from the directory containing `questions.yaml`.

```bash
coursebanks validate questions.yaml
```

A valid copy of the sample prints:

```text
Valid: COURSE123 / Module1_Conceptual: 1 questions
```

An invalid bank returns status `2` and prints an `ERROR:` diagnostic.
Read the first field named by the message, correct the YAML, save the file, and rerun validation until it succeeds.

Common corrections include:

- Align a field with the other fields in the same question when YAML reports a parsing or indentation error.
- Change a duplicate `id` or repeated question stem so each question is distinct.
- Make `answer` match one key under `choices` exactly.
- Use `Basic`, `Moderate`, or `Challenging` with the documented capitalization.
- Remove quotation marks around numeric `minutes` and `points` values.
- Add missing required fields and ensure text is not blank.

The [command troubleshooting guide](commands.md#troubleshooting) covers missing files, paths with spaces, and other diagnostics.

## 5. Build the Canvas package

Build all deliverables into a directory named `build`.

```bash
coursebanks build questions.yaml --out build
```

The sample prints a summary containing the archive path, question count, and SHA-256 digest.
The digest is a fingerprint that lets you identify the exact ZIP that was reviewed.

```text
Created build/COURSE123_Module1_Conceptual_QTI12.zip: 1 questions; SHA-256 ...
```

The build directory contains four files.

| File | Purpose |
| --- | --- |
| `COURSE123_Module1_Conceptual_QTI12.zip` | Upload this unopened ZIP file to Canvas. |
| `instructor_review.md` | Readable review of stems, choices, answer keys, explanations, and authoring metadata. |
| `question_catalog.csv` | Spreadsheet-friendly catalog for filtering questions by area, topic, difficulty, eligibility, time, and points. |
| `validation.json` | Machine-readable build record containing item IDs, counts, difficulty totals, and the ZIP digest. |

Open `instructor_review.md` and confirm the wording, answer, feedback, points, and intended choice shuffling before upload.
Do not give this instructor-only file to students because it contains answer keys.
Use `question_catalog.csv` for review and inventory; it is not the Canvas upload file.

Run the structural QTI check if the ZIP has been moved, renamed, or copied.

```bash
coursebanks check-qti build/COURSE123_Module1_Conceptual_QTI12.zip
```

A successful check prints `Valid QTI 1.2 structure: 1 questions`.
This local check verifies the toolkit's supported package structure but cannot predict every institutional Canvas setting or rendering difference.

## 6. Import and review in Canvas

Follow [Importing the generated package into Canvas](canvas-import.md) for separate Classic Quizzes, New Quizzes, and New Quizzes item-bank procedures.
Upload `COURSE123_Module1_Conceptual_QTI12.zip`, then preview every imported question before publishing or assigning it.

## Optional workflows

Importing an existing QTI archive back into YAML is covered in [Importing QTI into YAML](importing-qti.md).
Question selection, usage recording, and multi-term rotation planning are optional instructor workflows listed in the [command reference](commands.md#rotation-commands).
Git, editable installation, testing, linting, typing, and source contributions are covered in the [developer guide](development.md).