5.7 Scripts to ease doc work
5.7.1 Scripts to test the documentation
Building only one section of the documentation
In order to save build time, a script is available to build only
one section of the documentation in English with a default HTML
appearance.
If you do not yet have a ‘build/’ subdirectory within the LilyPond
Git tree, you should create this first. You can then build a section of
the documentation with the following command:
| | scripts/auxiliar/doc-section.sh MANUAL SECTION
|
where SECTION is the name of the file containing the section
to be built, and MANUAL is replaced by the name of the directory
containing the section. So, for example, to build section 1.1 of the
Notation Reference, use the command:
| | scripts/auxiliar/doc-section.sh notation pitches
|
You can then see the generated document for the section at
| | build/tempdocs/pitches/out/pitches.html
|
According to
LilyPond issue 1236,
the location of the LilyPond Git tree is taken from $LILYPOND_GIT
if specified, otherwise it is auto-detected.
It is assumed that compilation takes place in the ‘build/’
subdirectory, but this can be overridden by setting the environment
variable LILYPOND_BUILD_DIR.
Similarly, output defaults to ‘build/tempdocs/’ but this can be
overridden by setting the environment variable
LILYPOND_TEMPDOCS.
This script will not work for building sections of the
Contributors’ Guide. For building sections of the Contributors’
Guide, use:
| | scripts/auxiliar/cg-section.sh SECTION
|
where SECTION is the name of the file containing the sections
to be built. For example, to build section 4 of the Contributors’ Guide,
use:
| | scripts/auxiliar/cg-section.sh doc-work
|
cg-section.sh uses the same environment variables and
corresponding default values as doc-section.sh.
5.7.2 Scripts to create documentation
Stripping whitespace and generating menus
Note: This script assumes that the file conforms to our doc
policy, in particular with regard to Sectioning commands;
a few files still need work in this regard.
To automatically regenerate @menu portions and strip
whitespace, use:
| | scripts/auxiliar/node-menuify.py FILENAME
|
If you are adding documentation that requires new menus,
you will need to add a blank @menu section:
Stripping whitespace only
To remove extra whitespace from the ends of lines, run
| | scripts/auxiliar/strip-whitespace.py FILENAME
|
Updating doc with convert-ly
Don’t. This should be done by programmers when they add new
features. If you notice that it hasn’t been done, complain to
lilypond-devel.
This document was generated by gub on July 13, 2020 using texi2html 1.82.