.. _buildingDocumentation:


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.