.. _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 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.