Docs — Abjad v1.1.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Project Abjad »
- Abjad v1.1.1 documentation »

# Docs

The Abjad documentation is included in its entirety when you check out the Abjad codebase. You may add to and edit the docs as soon as you download and install Abjad. However, to build HTML or PDF versions of the docs and see the results of your changes you will first need to download and install Sphinx, the automated documentation build and management system used by Abjad and a number of other Python projects, including www.python.org.

This remaining sections of this chapter describe how to find and edit the Abjad docs, and how to build the the docs with Sphinx.

## How the docs are laid out

The Abjad documentation source files are included in the `documentation` directory of every Abjad download.

    abjad$ ls -d d*

    debug         directives    dots
    demos         documentation dynamics

The `documentation` directory contains everything required to build HTML, LaTeX and PDF versions of the Abjad docs, including the page that you’re reading now. List the contents of the `documentation` directory and take a look around.

    abjad$ ls documentation

    Makefile   _templates chapters   index.rst  scr
    _static    _themes    conf.py    make.bat

The core content of the Abjad docs lives in `documentation/chapters`.

    abjad$ ls documentation/chapters/

    api          background   fundamentals tutorial
    appendices   developers   introduction

The `documentation/chapters` subdirectories mirror the main sections on the front page of the Abjad docs.

What you’ll find as you inspect the chapters directories, or as you consider adding a new chapter directory, are a collection of `.rst` files organized into directories. The `.rst` extension identifies files written in restructured text, or reST, described more fully below. [1]

    abjad$ ls documentation/chapters/appendices/glossary

    index.rst

## Running `make clean`

After you have downloaded and installed Sphinx, change to the Abjad `documentation` directory and use the Sphinx makefile to remove any existing `documentation/_build` directory prior to making a new build of the docs.

    abjad$ cd documentation
    documentation$ make clean

    rm -rf _build/*

This removes the `documentation/_build` directory and its contents. After `make clean` feel free to build new HTML or other versions of of the docs as described in the following sections.

## Autogenerating the Abjad API

The `documentation/scr` directory includes a script to autogenerate the Abjad API. Run this script before building the main part of the docs for the first time.

    documentation$ scr/make-abjad-api
    Run script in interactive mode? [Y/n]: n

    Writing file /Users/trevorbaca/Documents/abjad/trunk/abjad/documentation/chapter
    s/api/accidental/accidental.rst ...
    Writing file /Users/trevorbaca/Documents/abjad/trunk/abjad/documentation/chapter
    s/api/accidental/interface.rst ...
    Writing file /Users/trevorbaca/Documents/abjad/trunk/abjad/documentation/chapter
    s/api/articulations/articulation.rst ...

    ... (many lines omitted) ...

    Writing file /Users/trevorbaca/Documents/abjad/trunk/abjad/documentation/chapter
    s/api/voice/voice.rst ...
    Writing file /Users/trevorbaca/Documents/abjad/trunk/abjad/documentation/chapter
    s/api/voice/interface/interface.rst ...
    Writing file /Users/trevorbaca/Documents/abjad/trunk/abjad/documentation/chapter
    s/api/index.rst ...

Rerun `make-abjad-api` any time you add or remove a public class, method or function from the codebase.

## Building the HTML docs

Change to the Abjad `documentation` directory and run `make html`.

    abjad$ cd documentation
    documentation$ make html

    Making output directory...
    Running Sphinx v0.6.1
    loading pickled environment... not found
    building [html]: targets for 568 source files that are out of date
    updating environment: 568 added, 0 changed, 0 removed
    reading sources... [ 13%] chapters/api/debug/debugghandlertoregatorsg
    reading sources... [ 37%] chapters/api/tools/clonewp/by_leaf_counts_with_parenta
    reading sources... [ 38%] chapters/api/tools/clonewp/by_leaf_range_with_parentag
    reading sources... [ 38%] chapters/api/tools/componenttools/get_duration_crosser
    reading sources... [ 38%] chapters/api/tools/componenttools/get_duration_preprol
    reading sources... [ 39%] chapters/api/tools/componenttools/get_le_duration_prol

    ... (many more lines omitted) ...

    writing output... [ 85%] chapters/api/tools/spannertools/give_attached_to_childr
    writing output... [ 95%] chapters/fundamentals/duration/interfaces_compared/inde
    writing output... [100%] index                  /indexdexexexng/indexxdexindex
    writing additional files... genindex modindex search
    copying images... done
    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 `documentation/_build/html`.

    documentation$ ls _build/
    doctress html

The output from Sphinx is verbose the first time you build the docs. On sequent builds, Sphinx reports changes only.

    documentation$ make html

    sphinx-build -b html -d _build/doctrees   . _build/html
    Running Sphinx v0.6.1
    loading pickled environment... done
    building [html]: targets for 1 source files that are out of date
    updating environment: 0 added, 1 changed, 0 removed
    reading sources... [100%] chapters/devel/documentation/index
    looking for now-outdated files... none found
    pickling environment... done
    checking consistency... done
    preparing documents... done
    writing output... [100%] index                  ation/index
    writing additional files... genindex modindex search
    copying static files... done
    dumping search index... done
    dumping object inventory... done
    build succeeded.

    Build finished. The HTML pages are in _build/html.

## Building a coverage report

Change to the Abjad `documentation` directory and call `sphinx-build` explicitly with the coverage builder, source directory and target directory.

    documentation$ sphinx-build -b coverage . _build/coverage
    Making output directory...
    Running Sphinx v0.6.1
    loading pickled environment... not found
    building [coverage]: coverage overview
    updating environment: 568 added, 0 changed, 0 removed
    reading sources... [ 37%] chapters/api/tools/clonewp/by_leaf_counts_with_parenta
    reading sources... [ 38%] chapters/api/tools/clonewp/by_leaf_range_with_parentag
    reading sources... [ 38%] chapters/api/tools/componenttools/get_duration_crosser

    ... (many lines omitted) ...

    reading sources... [ 85%] chapters/api/tools/spannertools/withdraw_from_containe
    reading sources... [ 95%] chapters/fundamentals/duration/interfaces_compared/ind
    reading sources... [100%] index                 t/indexdexexexng/indexxdexindex
    looking for now-outdated files... none found
    pickling environment... done
    checking consistency... done
    build succeeded.

The coverage report is now available in the `documentation/_build/coverage` directory.

    documentation$ ls _build/
    coverage doctrees html

## Building other versions of the docs

Examine the Sphinx makefile in the Abjad `documentation/` directory or change to the `documentation/` directory and type `make` with no arguments to see a list of the other versions of the Abjad docs that are available to build.

    documentation$ 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
      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
      latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
      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)

## Inserting images with `abjad-book`

Use abjad-book to insert snippets of notation in the docs you write in ReST.

Embed Abjad code between open and close <abjad> </abjad> tags in your `.rst.raw` sourcefile and then call `abjad-book` to create a pure `.rst` file.

    abjad-book foo.rst.raw foo.rst

    Parsing file ...
    Rendering "example-1.ly" ...
    Rendering "example-2.ly" ...

You will need to build the HTML docs again to see your work.

    make html

Footnotes

[1] | Restructured text is abbreviated reST or ReST and should not be confused with the REST and SOAP protocols in use in other development projects on the Web.

### Navigation

- index
- modules |
- next |
- previous |
- Project Abjad »
- Abjad v1.1.1 documentation »