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.

1) Install pip (if needed)

In order to get additional modules, you’ll need a way of getting them more easily. Recent versions of Python 2.7 and 3.4 include pip or pip3; if you don’t have it, you should download it. Just go to and they’ll help you out.

2) Install pandoc

Pandoc is a universal documentation converter that we use. You can get pandoc at:

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

3) Install nbconvert

Some of the tutorials and users guides for music21 use the Jupyter/IPython notebook. To convert these files to the Python documentation format .rst, you’ll need nbconvert (and pandoc). Run sudo pip3 install nbconvert or sudo pip3 install nbconvert. On Windows, omit the sudo. You will probably be asked for your password to install.

4) Downloading and Installing Sphinx

Sphinx is the document builder for Python. Run on Mac “sudo pip3 install sphinx” or on Windows “pip3 install sphinx”.

5) Run documentation/

Find the documentation folder within music21. And run with python or python3 the file, 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.

If you can’t find your music21 installation run these commands: from music21 import * and then common.getSourceFilePath().

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 python3 clean and you will have a clean directory to build again.