LilyPond Contributor's Guide: 4.6.2 Generating documentation

### 4.6.2 Generating documentation

#### Documentation editor’s edit/compile cycle

- Initial documentation build:

  >     make [-jX]
  >     make [-jX CPU_COUNT=X] doc  ## can take an hour or more

- Edit/compile cycle:

  >     ## edit source files, then...

  >     make [-jX]                  ## needed if editing outside
  >                                 ##   Documentation/, but useful anyway
  >                                 ##   for finding Texinfo errors.
  >     touch Documentation/*te??   ## bug workaround
  >     make [-jX CPU_COUNT=X] doc  ## usually faster than initial build.

- Reset:

  In some cases, it is possible to clean the compiled documentation with ‘`make doc-clean`’, but this method is not guaranteed to fix everything. Instead, we recommend that you delete your ‘`build/`’ directory, and begin compiling from scratch. Since the documentation compile takes much longer than the non-documentation compile, this does not increase the overall time by a great deal.

#### Building documentation

After a successful compile (using `make`), the documentation can be built by issuing:

>     make doc

The first time you run `make doc`, the process can easily take an hour or more. After that, `make doc` only makes changes to the pre-built documentation where needed, so it may only take a minute or two to test changes if the documentation is already built.

If `make doc` succeeds, the HTML documentation tree is available in ‘`out-www/offline-root/`’, and can be browsed locally. Various portions of the documentation can be found by looking in ‘`out/`’ and ‘`out-www`’ subdirectories in other places in the source tree, but these are only portions of the docs. Please do not complain about anything which is broken in those places; the only complete set of documentation is in ‘`out-www/offline-root/`’ from the top of the source tree.

Compilation of documentation in Info format with images can be done separately by issuing:

>     make info

#### Known issues and warnings

If source files have changed since the last documentation build, output files that need to be rebuilt are normally rebuilt, even if you do not run `make doc-clean` first. However, build dependencies in the documentation are so complex that some newly-edited files may not be rebuilt as they should be; a workaround is to `touch` the top source file for any manual you’ve edited. For example, if you make changes to a file in ‘`notation/`’, do:

>     touch Documentation/notation.tely

The top sources possibly affected by this are:

>     Documentation/extend.texi
>     Documentation/changes.tely
>     Documentation/contributor.texi
>     Documentation/essay.tely
>     Documentation/extending.tely
>     Documentation/learning.tely
>     Documentation/notation.tely
>     Documentation/snippets.tely
>     Documentation/usage.tely
>     Documentation/web.texi

You can `touch` all of them at once with:

>     touch Documentation/*te??

However, this will rebuild all of the manuals indiscriminately—it is more efficient to `touch` only the affected files.

#### Saving time with `CPU_COUNT`

The most time consuming task for building the documentation is running LilyPond to build images of music, and there cannot be several simultaneously running `lilypond-book` instances, so the ‘`-j`’ `make` option does not significantly speed up the build process. To help speed it up, the makefile variable ‘`CPU_COUNT`’ may be set in ‘`local.make`’ or on the command line to the number of `.ly` files that LilyPond should process simultaneously, e.g. on a bi-processor or dual core machine:

>     make -j3 CPU_COUNT=3 doc

The recommended value of ‘`CPU_COUNT`’ is one plus the number of cores or processors, but it is advisable to set it to a smaller value unless your system has enough RAM to run that many simultaneous LilyPond instances. Also, values for the ‘`-j`’ option that pose problems with ‘`make`’ are less likely to pose problems with ‘`make doc`’ (this applies to both ‘`-j`’ and ‘`CPU_COUNT`’). For example, with a quad-core processor, it is possible for ‘`make -j5 CPU_COUNT=5 doc`’ to work consistently even if ‘`make -j5`’ rarely succeeds.

#### AJAX search

To build the documentation with interactive searching, use:

>     make doc AJAX_SEARCH=1

This requires PHP, and you must view the docs via a http connection (you cannot view them on your local filesystem).

Note: Due to potential security or load issues, this option is not enabled in the official documentation builds. Enable at your own risk.

#### Installing documentation

The HTML, PDF and if available Info files can be installed into the standard documentation path by issuing

>     make install-doc

This also installs Info documentation with images if the installation prefix is properly set; otherwise, instructions to complete proper installation of Info documentation are printed on standard output.

To install the Info documentation separately, run:

>     make install-info

Note that to get the images in Info documentation, `install-doc` target creates symbolic links to HTML and PDF installed documentation tree in ‘`prefix/share/info`’, in order to save disk space, whereas `install-info` copies images in ‘`prefix/share/info`’ subdirectories.

It is possible to build a documentation tree in ‘`out-www/online-root/`’, with special processing, so it can be used on a website with content negotiation for automatic language selection; this can be achieved by issuing

>     make WEB_TARGETS=online doc

and both ‘offline’ and ‘online’ targets can be generated by issuing

>     make WEB_TARGETS="offline online" doc

Several targets are available to clean the documentation build and help with maintaining documentation; an overview of these targets is available with

>     make help

from every directory in the build tree. Most targets for documentation maintenance are available from ‘`Documentation/`’; for more information, see Documentation work.

The makefile variable `QUIET_BUILD` may be set to `1` for a less verbose build output, just like for building the programs.

#### Building documentation without compiling

The documentation can be built locally without compiling LilyPond binary, if LilyPond is already installed on your system.

From a fresh Git checkout, do

>     ./autogen.sh   # ignore any warning messages
>     cp GNUmakefile.in GNUmakefile
>     make -C scripts && make -C python
>     nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc

Please note that this may break sometimes – for example, if a new feature is added with a test file in input/regression, even the latest development release of LilyPond will fail to build the docs.

You may build the manual without building all the ‘`input/*`’ stuff (i.e. mostly regression tests): change directory, for example to ‘`Documentation/`’, issue `make doc`, which will build documentation in a subdirectory ‘`out-www`’ from the source files in current directory. In this case, if you also want to browse the documentation in its post-processed form, change back to top directory and issue

>     make out=www WWW-post

#### Known issues and warnings

You may also need to create a script for `pngtopnm` and `pnmtopng`. On GNU/Linux, I use this:

    export LD_LIBRARY_PATH=/usr/lib
    exec /usr/bin/pngtopnm "$@"

On MacOS X with fink, I use this:

    export DYLD_LIBRARY_PATH=/sw/lib
    exec /sw/bin/pngtopnm "$@"

On MacOS X with macports, you should use this:

    export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
    exec /opt/local/bin/pngtopnm "$@"

#### LilyPond — Contributor’s Guide