The reST-based sources for the Abjad documentation are included in their entirety in every installation of Abjad. You may add to and edit these reST-based sources as soon as you install Abjad. However, to build human-readable HTML or PDF versions of the docs you will first need to download and install Sphinx.
The remaining sections of this chapter describe how the Abjad docs are laid out and how to build the docs with Sphinx.
How the Abjad docs are laid out¶
The source files for the Abjad docs are included in the
docs directory of
every Abjad install. The
docs directory contains everything required to
build HTML, PDF and other versions of the Abjad docs:
abjad$ ls -x -F docs/ Makefile __init__.py __pycache__/ build/ ext/ make.bat source/
The documentation sourcefiles are collected in section directories resident in
abjad$ ls -x -F docs/source/ _static/ _stylesheets/ abstract.txt api/ appendices/ badges.txt conf.py cookbook/ core_concepts/ developer_documentation/ for_beginners/ gallery/ gallery.rst index.rst installation.rst links.txt literature_examples/ mothballed/ reference_manual/ tools/
The nine section directories in
docs/source mirror the frontpage sections
of the Abjad documentation. There are section directories for the start here,
system overview, examples, tutorials, reference manual, developer
documentation, appendices, and api and “in conversation” sections of
When you look inside a section directory you’ll find a collection of chaper directories.
Here are the reference manual chapter directories:
abjad$ ls -x -F docs/source/reference_manual annotations.rst articulations.rst chords.rst containers.rst index.rst instruments.rst lilypond_commands.rst lilypond_comments.rst lilypond_files.rst measures.rst named_pitches.rst notes.rst rests.rst scores.rst staves.rst tuplets.rst voices.rst
And when you look inside a chapter directory you’ll find an
.rst file and an
abjad$ ls -x -F docs/source/reference_manual/notes ls: docs/source/reference_manual/notes: No such file or directory
Sphinx is the automated documentation system used by Python, Abjad and other projects implemented in Python. Because Sphinx is not included in the Python standard library you will probably need to download and install it.
First check to see if Sphinx is already installed on your machine:
abjad$ sphinx-build --version Sphinx (sphinx-build) 1.5.5
If Sphinx responds then the program is already installed on your machine. Otherwise visit the Sphinx website.
ajv application ships with Abjad. The application helps developers
manage the Ajbad codebase. The
api allows for building
and cleaning various formats of Sphinx documentation.
abjad$ ajv api --help usage: build-api [-h] [--version] [-C] [-I] [-M] [-O] [-R] [-S] [-X] [--api-title API_TITLE] [--docs-directory DOCS_DIRECTORY] [--packages-to-document PACKAGES_TO_DOCUMENT] [--format FORMAT] Build the Abjad APIs. optional arguments: -h, --help show this help message and exit --version show program's version number and exit -C, --clean run "make clean" before building the api -I, --ide build the Abjad IDE API -M, --mainline build the mainline API -O, --open open the docs in a web browser after building -R, --rst-only generate the ReSt source files but do not build -S, --score-library build score library API -X, --experimental build the experimental API --api-title API_TITLE title of API --docs-directory DOCS_DIRECTORY documentation directory --packages-to-document PACKAGES_TO_DOCUMENT comma-delimited packages list (ex: "foo.tools,bar.tools") --format FORMAT Sphinx builder to use
Removing old builds of the documentation¶
To remove old builds of the documentation, use the
abjad$ ajv api --clean
Building the HTML docs¶
You can use
ajv to build the HTML docs. It doesn’t matter what directory
you’re in when you run the following command:
abjad$ ajv api -M Now writing ReStructured Text files ... ... done. Now building the HTML docs ... sphinx-build -b html -d build/doctrees source build/html Making output directory... Running Sphinx v1.1.3 loading pickled environment... not yet created loading intersphinx inventory from http://docs.python.org/2.7/objects.inv... building [html]: targets for 1131 source files that are out of date updating environment: 1131 added, 0 changed, 0 removed reading sources... [ 1%] api/demos/part/PartCantusScoreTemplate/PartCantusScore reading sources... [ 4%] api/tools/abjadbooktools/AbjadBookProcessor/AbjadBookP reading sources... [ 4%] api/tools/abjadbooktools/AbjadBookScript/AbjadBookScri reading sources... [ 4%] api/tools/abjadbooktools/HTMLOutputFormat/HTMLOutputFo reading sources... [ 4%] api/tools/abjadbooktools/LaTeXOutputFormat/LaTeXOutput reading sources... [ 4%] api/tools/abjadbooktools/ReSTOutputFormat/ReSTOutputFo reading sources... [ 5%] api/tools/scoretools/Chord/Chord ... ... ... copying images... [ 89%] reference_manual/lilypond_commands/images/index-2. copying images... [ 93%] tutorials/understanding_time_signatures/images/ind copying images... [ 94%] tutorials/working_with_threads/images/thread-resolution copying images... [100%] reference_manual/staves/images/index-8.png copying static files... done dumping search index... done dumping object inventory... done build succeeded. Build finished. The HTML pages are in build/html.
You will then find the complete HTML version of the docs in the
abjad$ ls docs/build/ doctrees html
The output from Sphinx is verbose the first time you build the docs. On sequent builds, Sphinx reports changes only:
abjad$ ajv api -M Now writing ReStructured Text files ... ... done. Now building the HTML docs ... sphinx-build -b html -d build/doctrees source build/html Running Sphinx v1.1.3 loading pickled environment... done building [html]: targets for 0 source files that are out of date updating environment: 0 added, 0 changed, 0 removed looking for now-outdated files... none found no targets are out of date. Build finished. The HTML pages are in build/html.
Building a PDF of the docs¶
Building a PDF of the docs is almost as simple as building the HTML documentation:
abjad$ ajv api -M --format latexpdf Now writing ReStructured Text files ... ... done. Now building the LATEXPDF docs ... sphinx-build -b latex -d build/doctrees source build/latex Running Sphinx v1.2b1 loading pickled environment... done building [latex]: all documents updating environment: 0 added, 1 changed, 0 removed reading sources... [100%] developer_documentation/index looking for now-outdated files... 10 found pickling environment... done checking consistency... done processing Abjad.tex.. ... ... ... Transcript written on AbjadAPI.log. pdflatex finished; the PDF files are in build/latex.
The resulting docs will appear as
AbjadAPI.pdf in the
LaTeX build directory,
Building a coverage report¶
Build the coverage report with
ajv api and the
abjad$ ajv api -M --format coverage Now writing ReStructured Text files ... ... done. Now building the COVERAGE docs ... Running Sphinx v1.2b1 loading pickled environment... done building [coverage]: coverage overview updating environment: 0 added, 1 changed, 0 removed reading sources... [100%] api/tools/commandlinetools/BuildAPIScript/BuildAPIScript looking for now-outdated files... none found pickling environment... done checking consistency... done build succeeded.
The coverage report is now available in the
docs$ ls build/ coverage doctrees html
Building other versions of the docs¶
Examine the Sphinx makefile in the Abjad
docs/ directory or change to the
docs/ directory and type
make with no arguments to see a list of the
other versions of the Abjad docs that are available to build:
docs$ make Please use "make <target>" where <target> is one of html to make standalone HTML files dirhtml to make HTML files named index.html in directories singlehtml to make a single large HTML file pickle to make pickle files json to make JSON files htmlhelp to make HTML files and a HTML help project qthelp to make HTML files and a qthelp project devhelp to make HTML files and a Devhelp project epub to make an epub latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter latexpdf to make LaTeX files and run them through pdflatex text to make text files man to make manual pages texinfo to make Texinfo files info to make Texinfo files and run them through makeinfo gettext to make PO message catalogs changes to make an overview of all changed/added/deprecated items linkcheck to check all external links for integrity doctest to run all doctests embedded in the documentation (if enabled) book to run abjad-book on all ReST files in source
It is important periodically to update your version of Sphinx. If you used
pip to install Sphinx then the usual command to update Sphinx is
abjad$ sudo pip install --upgrade Sphinx