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


**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 https://pip.pypa.io/ and they'll help you out.

**2) Install pandoc**

Pandoc is a universal documentation converter that we use.
You can get pandoc at: http://pandoc.org/installing.html

**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 pip 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 pip install sphinx" 
or on Windows "pip install sphinx".  

**5) Run documentation/make.py** 

Find the documentation folder within `music21`. And run with python or python3 
the `make.py` 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 make.py clean` and you will have a clean directory to
build again.