Building Documentation

Creating or updating the music21 documentation requires a few additional programs to be installed, most importantly one called Sphinx. Sphinx is a documentation generator that uses reStructuredText (rst) as its markup language and outputs HTML documents.

In addition, you will need a copy of the git repository (https://github.com/cuthbertLab/music21).

1) Install uv and run uv sync

Get uv at https://docs.astral.sh/uv/ and then, in the music21 directory, run uv sync. This installs Sphinx, Jupyter, and nbconvert, which turns the Jupyter notebooks used in the tutorials and User’s Guide into .rst files.

2) Install pandoc

Pandoc is a universal documentation converter that we use (nbconvert needs it). You can get pandoc at: https://pandoc.org/installing.html

Note that pandoc 1.14-1.15.0 do not work. 1.15.1 and newer are recommended.

3) Run documentation/make.py

From the music21 directory run uv run documentation/make.py, which will automatically build all the music modules in music21 into the “autogenerated” folder and from there into the “build/html” folder. It should also open your web browser automatically.

The first time you build the documentation, it’ll take a long time. Subsequent builds, however, only build the parts that have changed. If you need to build from scratch, run uv run documentation/make.py clean and you will have a clean directory to build again.