Author Documentation

Why This Exists

The project has two public-facing entry points:

  • the command-line tool in code/main.py for generating and rendering material

  • the thesis companion page in webpage/index.html for browsing numbered examples

This documentation sits between those two layers. It explains how code, generated assets, and thesis references fit together so you can update one part of the project without losing track of the others.

Main Asset Paths

  • code/output/<seed>/ stores generated LilyPond, PDF, MIDI, and WAV files

  • thesis/latex/examples/ stores curated example assets referenced from the thesis

  • thesis/latex/main.pdf is the thesis document itself

  • webpage/index.html links examples back into the thesis by page number

Typical Thesis Example Workflow

  1. Generate a melody or example asset with code/main.py.

  2. Render the cropped PDF and optional WAV output.

  3. Copy or curate the relevant files into thesis/latex/examples/ when the example becomes part of the thesis.

  4. Add the numbered example to webpage/index.html so the browser archive mirrors the thesis structure.

  5. Rebuild the docs if the CLI, engine structure, or workflow description changed.

Deployment Workflow

The deploy script in webpage/deploy.zsh publishes four things together:

  • the webpage itself

  • the thesis PDF

  • the generated documentation in docs/_build/html/

  • the thesis example assets

Before copying files, the deploy script rebuilds the thesis PDF, regenerates the archive page from the LaTeX example environments and main.aux labels, and rebuilds the documentation. That means newly added thesis examples are picked up by the webpage during deployment instead of being maintained by hand.

GitHub Pages Deployment

The GitHub Pages deployment script in webpage/deploy_github_pages.zsh builds the same archive and documentation, copies the static files into a separate gh-pages worktree, commits them, and pushes the branch to GitHub.

Run it from the repository root:

./webpage/deploy_github_pages.zsh

You can also provide the commit message directly:

./webpage/deploy_github_pages.zsh "Deploy updated thesis examples"

The first time this is used, GitHub Pages still needs to be enabled once in the repository settings with the source set to the gh-pages branch root.