Music21’s documentation system uses a combination of handwritten documentation pages (like this one), and documentation automatically generated from the documentation found in modules.
For handwritten pages, the files can be found in the top-level /buildDoc/rst/ directories, outside the music21 directory. The files are written using the reStructuredText format (file extension: .rst), which is a pretty simple way of defining structure of documents with things such as hyperlinks, emphasis, etc. We then use the excellent module Sphinx along with our custom-made build.py to translate the code to .html (what you’re reading here) and store that code in /music21/doc/html – letting you read it offline. (And of course we put a copy of that code online.)
But most 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 – we’re sort of bastards in how we look out for the users who will come after you – but we’ll help you learn the ropes. This doc explains some of the main features (and potential Gotchas!) of our automatic documentation system.
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/build.py 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:
easy_install -U Sphinx
easy_install rst2pdf
Sphinx uses special characters to identify formatting of documentation. For example, to write a heading you can write: Helpful tips on Sphinx formatting may be found here: Sphinx Documentation Formatting
The code would look like this:
**This is bold**
The documentation looks like this: This is bold
The code would look like this:
*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:
:meth:`~music21.note.GeneralNote.addLyric`
The documentation looks like this: addLyric()
Or you would like to link to another class, write:
:class:`~music21.note.Note`
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. For example, in your code write:
...blah blah blah this text is formatted. now I'm ready for not-formatted text, so I put two colons::
this text is NOT formatted
it must be indented
line breaks and spacing is preserved
**bold** sphinx formatting is not observed
Now I'm back to sphinx formatting...**now this is bold!*
The documentation looks like this:
...blah blah blah this text is formatted. now I’m ready for not-formatted text, so I put two colons:
this text is NOT formatted
it must be indented
line breaks and spacing is preserved
**bold** sphinx formatting is not observed
Now I’m back to sphinx formatting. now this is bold!
We use doctests a lot in music21 – if you run /music21/test/test.py, it will run not only all the code in class Test() but also all the code in the documentation preceeded 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