explain the publishing process

extras/lib/school.py

@@ -144,6 +144,9 @@ class SchoolText:
 
 # text that contains / is adjacent to prefixes above, which are allowed for both schools
 EXEMPT = [
+    '{% if id == "columbia" %}` and `{% if id == "nyu" %}',
+    "`columbia-only` or `nyu-only`",
+    "`columbia` and `nyu` branches",
     ".zoom.us/rec",
     "autograder",  # matches "grader"
     "baseurl: ",  # _config.yml

extras/scripts/school_ci.sh

@@ -7,7 +7,6 @@ set -x
 SCHOOL=$1
 
 # remove irrelevant files
-
 git rm -r \
     .vscode/ \
     nbdime_config.json \

meta/instructor_guide.md

@@ -25,6 +25,25 @@ make slides lec=N
 
 The site is generated using [JupyterBook](https://jupyterbook.org/) and deployed to [ReadTheDocs](https://readthedocs.org/). Markdown (`.md`) files and the files and folders that start with an underscore (`_`) are related to JupyterBook.
 
+### Publishing
+
+This repository produces separate versions of the course site for Columbia and NYU. The source of truth is the `main` branch; the `columbia` and `nyu` branches contain generated, school-specific source files and their rendered sites.
+
+For each school, [the workflow](../.github/actions/setup/action.yml):
+
+1. Checks out the repository and installs the Python dependencies.
+1. Switches to the corresponding school branch and merges the pushed branch using Git's `ours` strategy. It then restores the pushed branch's working tree. This records that the school branch includes the source revision without using the school branch's generated files as merge inputs.
+1. Commits that preliminary source tree.
+1. Runs [`school_ci.sh`](../extras/scripts/school_ci.sh) with the school ID. The script removes files that do not belong in a published school version, including development tools and tests.
+1. Calls [`school.sh`](../extras/scripts/school.sh) to render school-specific templates.
+   - Jinja templating is used throughout the source files (Markdown, notebooks, etc.), rendered using [nbconvert](https://nbconvert.readthedocs.io/) with [a custom preprocessor](../extras/lib/school_template.py).
+   - Variables (such as `{{school_name}}`, `{{lms_url}}`, and `{{assistant_name}}`) are replaced with the values from the [configuration file](../extras/lib/school.py) for the selected school.
+   - It uses {% raw %}`{% if id == "columbia" %}` and `{% if id == "nyu" %}`{% endraw %} conditionals for school-only content; the generated files must contain neither Jinja tags nor identifiers for the other school.
+   - For notebooks, `school.sh` first removes cells tagged for the other school (`columbia-only` or `nyu-only`) and cells tagged `remove`. It then renders each remaining cell source with the same Jinja variables, while resetting notebook kernel metadata to the default Python kernel for Colab.
+1. Runs `make site`, which builds the Jupyter Book HTML into `_build/html`.
+1. When the push is to `main`, the workflow pushes the amended commit to the relevant school branch. Pushes to other branches still render both versions and upload their HTML, but do not update either published branch.
+1. ReadTheDocs is notified of updates to the school-specific branches, which are then built as separate [versions](https://docs.readthedocs.com/platform/stable/versions.html).
+
 The HTML can be downloaded as an [artifact](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow) from [the latest `Publish` Action](https://github.com/afeld/python-public-policy/actions/workflows/publish.yml).
 
 ### Building locally