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 to install music21 from the .tar.gz file on Github (https://github.com/cuthbertLab/music21/releases) or from the git repository (git://github.org/cuthbertLab/music21.git).

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 include pip or pip3; if you don’t have it, you should download it. Just go to https://pip.pypa.io/en/stable and they’ll help you out.

2) Install pandoc

Pandoc is a universal documentation converter that we use. 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) 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. 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/make.py

Find the documentation folder within the base folder of music21. Change directory to that directory and then run python3 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.

If you can’t find your music21 installation run these commands: from music21 import * and then common.getSourceFilePath(). The documentation directory is the directory above this named documentation.

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