LilyPond Contributor's Guide: 4.6.2 Generating documentation

[ << Compiling ]	[Top][Contents]	[ Documentation work >> ]
[ < Installing LilyPond from a local build ]	[ Up : Post-compilation options ]	[ Documentation editor's edit/compile cycle > ]

4.6.2 Generating documentation

Three levels of documentation are available for installation. The following table lists them in order of increasing complexity, along with the command sequence to install each.

Level	Images	Web	Command
Reduced Info	no	no	make && make install
Full Info	Yes	no	make && make info && make install-info
Web	yes	yes	make && make doc && make install-doc

The web documentation includes all info files, images, and web documents. The reduced info option omits images and info files that are either highly dependent upon images, or discuss technical program details.

[ << Compiling ]	[Top][Contents]	[ Documentation work >> ]
[ < Generating documentation ]	[ Up : Generating documentation ]	[ Building documentation > ]

Documentation editor’s edit/compile cycle

To work on a manual, do the following

Build lilypond itself
```
make [-jX]
```

Then build the specific manual to work on, and inspect:

## edit source files, then…
make CPU_COUNT=X -C Documentation out=www out-www/LANGUAGE/MYMANUAL.pdf

## if you prefer checking HTML files
make CPU_COUNT=X -C Documentation out=www out-www/LANGUAGE/MYMANUAL/index.html

To remove compiled documentation from your system, use ‘make doc-clean’ in the toplevel build directory.

[ << Compiling ]	[Top][Contents]	[ Documentation work >> ]
[ < Documentation editor's edit/compile cycle ]	[ Up : Generating documentation ]	[ Building a single document > ]

Building documentation

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

make doc

or, to build only the PDF documentation and not the HTML,

make -C Documentation out=www pdf

Note: The first time you run make doc, the process can easily take an hour or more with not much output on the command line.

After this initial build, make doc only makes changes to the 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. The documentation can also be inspected in the ‘Documentation/out-www’ subdirectory.

make doc sends the output from most of the compilation to logfiles. If the build fails for any reason, it should print the name of a logfile, explaining what failed.

make doc compiles the documents for all languages. To save some compile time, the English language documents can be compiled on their own with:

make LANGS='en' doc

Similarly, it is possible to compile a subset of the translated documentation by specifying their language codes on the command line. For example, the French and German translations are compiled with:

make LANGS='de fr' doc

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

make info

An issue when switching branches between master and translation is the appearance/disappearance of translated versions of some manuals. If you see such a warning from make:

No rule to make target `X', needed by `Y'

Your best bet is to delete the file Y.dep and to try again.

[ << Compiling ]	[Top][Contents]	[ Documentation work >> ]
[ < Building documentation ]	[ Up : Generating documentation ]	[ Saving time with CPU_COUNT > ]

Building a single document

It’s possible to build a single document. For example, to rebuild only ‘contributor.pdf’, do the following:

cd build/
cd Documentation/
touch ../../Documentation/en/contributor.texi
make out=www out-www/en/contributor.pdf

If you are only working on a single document, test-building it in this way can give substantial time savings - recreating ‘contributor.pdf’, for example, takes a matter of seconds.

[ << Compiling ]	[Top][Contents]	[ Documentation work >> ]
[ < Building a single document ]	[ Up : Generating documentation ]	[ Installing documentation > ]

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 dual core machine:

make -j2 CPU_COUNT=2 doc

The recommended value of ‘CPU_COUNT’ is the number of cores. If the build runs into out-of-memory problems, use a lower number.

[ << Compiling ]	[Top][Contents]	[ Documentation work >> ]
[ < Saving time with CPU_COUNT ]	[ Up : Generating documentation ]	[ Building documentation without compiling > ]

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. The final installation of Info documentation (integrating it into the documentation directory) is 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.

[ << Compiling ]	[Top][Contents]	[ Documentation work >> ]
[ < Installing documentation ]	[ Up : Generating documentation ]	[ Testing LilyPond binary > ]

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

This may break: 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

[ << Compiling ]	[Top][Contents]	[ Documentation work >> ]
[ < Installing documentation ]	[ Up : Generating documentation ]	[ Testing LilyPond binary > ]