Documenting music21

Music21’s documentation system uses a combination of a few handwritten documentation pages (like this one), a lot of Jupyter notebooks (mainly in the User’s Guide sections), and documentation automatically generated from the documentation found in modules (in moduleReference).

The handwritten pages and Jupyter notebooks are found in the /documentation/source/ directories. The automatically generated documentation is found in each .py module.

To build music21 documentation, go to the /documentation/ folder and run:


(At present, only MIT affiliates can run the script.)

.rst format files

The handwritten .rst files are written using the reStructuredText format, which is a pretty simple way of defining structure of documents with things such as hyperlinks, emphasis, etc. It is somewhat similar to Markdown format. These files should not contain code examples, since they will not be tested. (You may find some older files that do contain code; we should be translating these in the future).

These files get converted to .html when you run /documentation/ so long as the excellent module Sphinx has been installed.

You can also edit these .rst files directly in Jupyter notebook, which will make them show the layout as well.

Jupyter Notebook (.ipynb) files

Since 2013, the majority of new documentation should be written in Jupyter Notebook (formerly IPython Notebook) format. These files should never be edited directly, but instead should be edited using Jupyter Notebook running Python 3.6 or higher.

A lot of the music21 documentation is automatically generated from the documentation strings found in music21 modules. We strongly encourage other module writers to create documentation that works the same way. In fact, we won’t add your module to the music21 repository without documentation in this form – there’s a test that ensures that code coverage increases with each build – but we’ll help you learn the ropes. This doc explains some of the main features (and potential Gotchas!) of our automatic documentation system.

Install Jupyter with:

pip3 install jupyter

And then run it by changing directory to the direction you want to edit and run:

jupyter notebook

When editing examples with code be sure, at least the first time, to run each code excerpt individually and pay attention to changes in output and unexpected errors.

Documenting modules and classes

music21 documentation for modules is found inside the module itself, at the very top and before the import statements. This module-level documentation, usually in triple-quoted strings, might look like this:

I am documentation for this module!

The buildDoc/ script creates RST files for modules, which are processed by Sphinx. Place all documentation for public modules, module-level functions, classes, and class-level attributes, properties, and methods as close to the relevant code as possible.

If you’re going to edit docs you’ll need the latest version of Sphinx. Go to the command line and type:

pip3 install sphinx

Sphinx uses special characters to identify formatting styles in documentation. Helpful tips on Sphinx formatting may be found here: Sphinx Cheat Sheet

For example, the heading of this section was created by writing:

Documenting modules and classes

To write boldface you would write:

**This is bold**

The documentation looks like this: This is bold

To italicize, you would write:

*This is italics*

The documentation looks like this: This is italics

This is a one-line code sample:

``print variableName``

The documentation looks like this: print variableName

You may also use links in your documentation. For example, if in one method you’d like to link to another method’s documentation, write:


The documentation looks like this: addLyric()

Or to link to another class, write:


The documentation looks like this: Note

Sometimes pictures are useful to visually describe code to readers or to show the results of a .show() method call, etc. This is easy with sphinx. Just copy and paste the picture you’d like to use into the buildDoc/rst/images folder, and reference it in your documentation like this:

.. image:: images/completebach.*
    :width: 300

The documentation looks like this:


Finally, if there is a section of your documentation that you’d rather Sphinx not format at all, append two colons to the last line of formatted text, followed by a space, followed by the indented text block, followed by a space. Text written after this space will be formatted. This is useful for block-quoting example code. For example, in your code write:

...blah blah blah this text is formatted. Now I want to block-quote
some example code, so I put two colons::

    this text IS NOT formatted
    it must be indented

    line breaks AND spacing will be preserved
    **bold** sphinx formatting unobserved

Now I am back to Sphinx formatting, outside the block. **now this is bold!**

The documentation looks like this:

…blah blah blah this text is formatted. Now I want to block-quote some example code, so I put two colons:

this text IS NOT formatted
it must be indented

line breaks AND spacing will be preserved
**bold** sphinx formatting unobserved

Now I am back to Sphinx formatting, outside the block. now this is bold!

Displaying only some of the test code in the documentation

We use doctests a lot in music21 – if you run /music21/test/, it will run not only all the code in class Test() but also all the code in the documentation preceded by ‘>>>’ marks. This way our documentation and our test code doesn’t get out of sync with each other. Pretty cool, eh?

Here’s the thing: good programming means that you test as much as possible in the code, but good documentation means showing enough example code that the readers get it, but not so much that they want to claw out their own eyeballs. So how to proceed? Simply add the line “OMIT_FROM_Docs” in ALL CAPS instead of lowercase. (I can’t write it in all caps here or nothing else will display!)

Anything after that line in your documentation code won’t display. For instance, say we wanted to demonstrate the difference between and note.step, but also wanted to test to make sure that flats and sharps both were equally eliminated. We could write documentation/test-code like this (but with all caps)

>>> from music21 import *
>>> c1 = note.Note('C#')
>>> c1.step


(N.B. That should be capital DOCS above...)

>>> c2 = note.Note('C-')
>>> c2.step

and what you’ll get in your documentation is:

>>> from music21 import *
>>> c1 = note.Note('C#')
>>> c1.step

Lines can be omitted on an individual basis by adding the expression “#_DOCS_Hide” (again in all caps) somewhere on the line. On the other hand, the text “#_DOCS_Show” (again in all caps) is removed from any line before it appears in the documentation. So you could use some of the same lines to test code and also to give an example like so:

>>> d1 = note.Note("D-")
>>> assert( == 'D-')  #_DOCS_Hide
>>> #_DOCS_Show'lily.png')

in this case, the assertion code is omitted from the documentation generated from the module, while the lilypond file is not generated during doctests. It will look to your users like:

>>> d1 = note.Note("D-")

Together with OMIT_FROM_Docs, it’s a great way to have your cake and eat it too. (remember that these need to be in all caps)

Ordering Module-Level Class Names and Module-Level Functions

Classes are by default presented in the order in which they appear in the module. Module-level functions are by default sorted alphabetically. If that’s not what you want, then create a list called _DOC_ORDER which is a list of the class and/or function names in the module. These values are given as evaluated names, not strings.

Since this list uses classes and not strings, this list must come at the end of the module, after the Test classes and before calling music21.mainTest()

At the end of for instance, we write:

_DOC_ORDER = [Note, Rest]

if __name__ == "__main__":

Ordering Class-Level Names

Classes can define a _DOC_ORDER attribute which functions the same as the module-level _DOC_ORDER, that is it defines the order of attributes, properties, and/or methods in the class.

Unlike for top-level names, these values are given as strings, not evaluated names. The _DOC_ORDER attribute must be defined outside of the __init__() method to ensure that these values can be read from a Class object and not just instances.

The following abbreviated example is from

class Pitch(music21.Music21Object):
    '''Class doc strings.
    # define order to present names in documentation; use strings
    _DOC_ORDER = ['name', 'nameWithOctave', 'step', 'pitchClass', 'octave', 'midi']

    def __init__(self, name=None):

Documenting Class-Level Properties

To document a property do something like this:

def _getName(self):
   return self._storedName

def _setName(self, newName):
   if newName == 'Cuthbert':
       raise Exception("what a dumb name!")
       self._storedName = newName

name = property(_getName, _setName, doc = '''
      The name property stores a name for the object
      unless the name is something truly idiotic.

Documenting Class-Level Attributes

Class-level attributes, names that are neither properties not methods, can place their documentation in a dictionary called _DOC_ATTR. The keys of the dictionary are strings (not evaluated names) corresponding to the name of the attribute, and the value is the documentation.

Like _DOC_ORDER, don’t put this in __init__().

Here’s an example from

class Note(NotRest):
    Class doc string goes here.
    isNote = True
    isRest = False

    # define order to present names in documentation; use strings
    _DOC_ORDER = ['duration', 'quarterLength', 'nameWithOctave', 'pitchClass']

    # documentation for all attributes (that are not properties or methods)
    _DOC_ATTR = {
    'isNote': 'Boolean read-only value describing if this object is a Note.',
    'isRest': 'Boolean read-only value describing if this is a Rest.',
    'beams': 'A :class:`music21.note.Beams` object.',
    'pitch': 'A :class:`music21.pitch.Pitch` object.',

    def __init__(self, *arguments, **keywords):

If a _DOC_ATTR attribute is not defined, the most-recently inherited _DOC_ATTR attribute will be used. To explicitly merge an inherited _DOC_ATTR attribute with a locally defined _DOC_ATTR, use the dictionary’s update() method.

The following abbreviated example, showing the updating of the _DOC_ATTR inherited from NotRest, is from

class Chord(note.NotRest):
    Class doc strings.
    isChord = True
    isNote = False
    isRest = False

    # define order to present names in documentation; use strings
    _DOC_ORDER = ['pitches']
    # documentation for all attributes (not properties or methods)
    _DOC_ATTR = {
    'isNote': 'Boolean read-only value describing if this object is a Chord.',
    'isRest': 'Boolean read-only value describing if this is a Rest.',
    'beams': 'A :class:`music21.note.Beams` object.',
    # update inherited _DOC_ATTR dictionary

    def __init__(self, notes = [], **keywords):

However, you will rarely need to do this, since the documentation will point to the inherited docs automatically.

Documenting Class-Level Methods

This is the most common type of documentation, and it ensures both excellent documentation and doctests. A typical example of source code might look like this:

class className():

    [instance variables, __init__, etc.]

    def myNewMethod(self,parameters):
        This is documentation for this method

        >>> myInstance = className()
        >>> myInstance.myNewMethod(someParameters)
        >>> myUnicorn.someInstanceVariable
        [method code]