Changeset 62efd4c in rtems-docs for README.txt


Ignore:
Timestamp:
02/19/19 23:11:37 (5 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
5, master
Children:
1a051fc
Parents:
fb72a00
git-author:
Chris Johns <chrisj@…> (02/19/19 23:11:37)
git-committer:
Chris Johns <chrisj@…> (02/27/19 23:22:54)
Message:

waf: Change --sphinx-verbose to --sphinx-options, add --sphinx-nit-pick

Provide options to manage sphinx. Make using the nit-picky mode simpler
to access.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • README.txt

    rfb72a00 r62efd4c  
    4646
    4747We prefer being able to build images from source. This is not always possible
    48 so SVG format is preferred with generated PNG images so make sure the quality
     48so SVG format is preferred with generated PNG images to make sure the quality
    4949is consistent when building PDF output.
     50
     51Building images requires the source with an apporoiate file extension
     52is placed in the images directory. The built output image is written
     53back to the images directory. All images may be built or rebuilt when
     54building images is enabled via the waf configure command line. Please
     55only add and commit those images that have changed.
     56
     57We support building images in:
     58
     591. PlantUML (.puml), enable with `--plantuml`
     60
     612. Ditaa (.ditaa), enable with `--ditaa`
    5062
    5163We support the PlantUML image language. The PlantUML home page is:
     
    327339
    328340  $ ./waf configure [--pdf] [--singlehtml] [--prefix] \
    329                     [--sphinx-verbose] [--disable-extra-fonts]
     341                    [--sphinx-options] \
     342                    [--sphinx-nit-pick] \
     343                    [--plantuml] \
     344                    [--ditaa] \
     345                    [--disable-extra-fonts]
     346
    330347  $ ./waf
    331348
    332349The '--pdf' and '--singlehtml' options can be added to configure to build those
    333350output formats.
     351
     352Sphinx options can be added using the `--sphinx-options` option. If you have
     353more than option use a quoted argument. This is an advanced feature that can
     354be useful when experimenting with the `sphinx-build` command.
     355
     356Sphinx nit-picky mode adds `-n` to the `sphinx-build` command line to generate
     357warnings and extra information about the source to help make sure our
     358documentation source is as clean as possible. Please use this when writing
     359documentation or making updates.
    334360
    335361The '--disable-extra-fonts' allows you to build PDF documents with out the
     
    342368  $ ./waf build install
    343369
     370To build the PlantUML and Ditaa images:
     371
     372  $ ./waf configure --plantuml --ditaa
     373  $ ./waf clean build
     374
     375To nit-pick the source use:
     376
     377  $ ./waf configure --sphinx-nit-pick
     378  $ ./waf clean build
     379
    344380If you need to debug what is happening use configure with a suitable Sphinx
    345 version level:
    346 
    347   $ ./waf configure --sphinx-verbose=-v
     381verbose level:
     382
     383  $ ./waf configure --sphinx-options "-V -V"
    348384  $ ./waf clean build
    349385
Note: See TracChangeset for help on using the changeset viewer.