Changeset 62efd4c in rtems-docs


Ignore:
Timestamp:
Feb 19, 2019, 11:11:37 PM (5 months ago)
Author:
Chris Johns <chrisj@…>
Branches:
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.

Files:
2 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
  • common/waf.py

    rfb72a00 r62efd4c  
    2828        cfgs += ' -D %s=%s' % (c, configs[c])
    2929    rule = "${BIN_SPHINX_BUILD} %s -b %s -c %s %s -d %s %s %s %s ${SRC}" % \
    30            (sphinx_verbose(ctx), build_type, conf_dir, version_cmdline(ctx),
     30           (sphinx_options(ctx), build_type, conf_dir, version_cmdline(ctx),
    3131            doctrees, cfgs, source_dir, output_dir)
    3232    return rule
     
    112112    return ver
    113113
    114 def sphinx_verbose(ctx):
    115     return ' '.join(ctx.env.SPHINX_VERBOSE)
     114def sphinx_options(ctx):
     115    return ' '.join(ctx.env.SPHINX_OPTIONS)
    116116
    117117def is_top_build(ctx):
     
    200200        ctx.end_msg("yes (%s)" % ".".join(map(str, ver)))
    201201
    202         ctx.start_msg("Checking Sphinx Verbose ")
    203         if 'SPHINX_VERBOSE' not in ctx.env:
    204             ctx.env.append_value('SPHINX_VERBOSE', ctx.options.sphinx_verbose)
    205             level = sphinx_verbose(ctx)
    206             if level == '-Q':
    207                 level = 'quiet'
    208             ctx.end_msg(level)
     202        ctx.start_msg("Checking Sphinx Options ")
     203        if 'SPHINX_OPTIONS' not in ctx.env:
     204            ctx.env.append_value('SPHINX_OPTIONS', ctx.options.sphinx_options)
     205            opts = sphinx_options(ctx)
     206            if len(opts) == 0:
     207                opts = 'none'
     208            ctx.end_msg(opts)
     209
     210        ctx.start_msg("Checking Sphinx Nit-Pick mode ")
     211        if ctx.options.sphinx_nit_pick:
     212            opt = '-n'
     213            msg = 'yes'
     214        else:
     215            opt = '-Q'
     216            msg = 'no'
     217        ctx.env.append_value('SPHINX_OPTIONS', opt)
     218        ctx.end_msg(msg)
     219
    209220        #
    210221        # Check extensions.
     
    429440                   default = False,
    430441                   help = "Disable building with extra fonts for better quality (lower quality).")
    431     ctx.add_option('--sphinx-verbose',
     442    ctx.add_option('--sphinx-options',
    432443                   action = 'store',
    433                    default = "-Q",
    434                    help = "Sphinx verbose.")
     444                   default = "",
     445                   help = "Additional Sphinx options.")
     446    ctx.add_option('--sphinx-nit-pick',
     447                   action = 'store_true',
     448                   default = False,
     449                   help = "Enable Sphinx nit-picky mode else be quiet")
    435450    ctx.add_option('--pdf',
    436451                   action = 'store_true',
Note: See TracChangeset for help on using the changeset viewer.