diff options
| -rw-r--r-- | README.txt | 44 | ||||
| -rw-r--r-- | common/waf.py | 41 |
2 files changed, 68 insertions, 17 deletions
@@ -45,9 +45,21 @@ All images should be placed int he 'images' directory and referenced from the ReST with a relative path. This lets us shared and control images. We prefer being able to build images from source. This is not always possible -so SVG format is preferred with generated PNG images so make sure the quality +so SVG format is preferred with generated PNG images to make sure the quality is consistent when building PDF output. +Building images requires the source with an apporoiate file extension +is placed in the images directory. The built output image is written +back to the images directory. All images may be built or rebuilt when +building images is enabled via the waf configure command line. Please +only add and commit those images that have changed. + +We support building images in: + +1. PlantUML (.puml), enable with `--plantuml` + +2. Ditaa (.ditaa), enable with `--ditaa` + We support the PlantUML image language. The PlantUML home page is: http://plantuml.com/ @@ -326,12 +338,26 @@ Note: waf-1.9.5 is a little noisy when running tex builds and tests. I hope To build enter in the top directory: $ ./waf configure [--pdf] [--singlehtml] [--prefix] \ - [--sphinx-verbose] [--disable-extra-fonts] + [--sphinx-options] \ + [--sphinx-nit-pick] \ + [--plantuml] \ + [--ditaa] \ + [--disable-extra-fonts] + $ ./waf The '--pdf' and '--singlehtml' options can be added to configure to build those output formats. +Sphinx options can be added using the `--sphinx-options` option. If you have +more than option use a quoted argument. This is an advanced feature that can +be useful when experimenting with the `sphinx-build` command. + +Sphinx nit-picky mode adds `-n` to the `sphinx-build` command line to generate +warnings and extra information about the source to help make sure our +documentation source is as clean as possible. Please use this when writing +documentation or making updates. + The '--disable-extra-fonts' allows you to build PDF documents with out the fonts we use for a better quality document. Use this option to build without needing the extra fonts accepting you will get poor quality documents. @@ -341,10 +367,20 @@ To build and install to a specific location: $ ./waf configure --prefix=/foo/my/location $ ./waf build install +To build the PlantUML and Ditaa images: + + $ ./waf configure --plantuml --ditaa + $ ./waf clean build + +To nit-pick the source use: + + $ ./waf configure --sphinx-nit-pick + $ ./waf clean build + If you need to debug what is happening use configure with a suitable Sphinx -version level: +verbose level: - $ ./waf configure --sphinx-verbose=-v + $ ./waf configure --sphinx-options "-V -V" $ ./waf clean build You can enter a manual's directory and run the same configure command and build diff --git a/common/waf.py b/common/waf.py index d3bfbbf..949d693 100644 --- a/common/waf.py +++ b/common/waf.py @@ -27,7 +27,7 @@ def sphinx_cmdline(ctx, build_type, conf_dir, doctrees, for c in configs: cfgs += ' -D %s=%s' % (c, configs[c]) rule = "${BIN_SPHINX_BUILD} %s -b %s -c %s %s -d %s %s %s %s ${SRC}" % \ - (sphinx_verbose(ctx), build_type, conf_dir, version_cmdline(ctx), + (sphinx_options(ctx), build_type, conf_dir, version_cmdline(ctx), doctrees, cfgs, source_dir, output_dir) return rule @@ -111,8 +111,8 @@ def check_sphinx_version(ctx, minver): ctx.fatal("Sphinx version is too old: %s" % ".".join(map(str, ver))) return ver -def sphinx_verbose(ctx): - return ' '.join(ctx.env.SPHINX_VERBOSE) +def sphinx_options(ctx): + return ' '.join(ctx.env.SPHINX_OPTIONS) def is_top_build(ctx): from_top = False @@ -199,13 +199,24 @@ def cmd_configure(ctx): ver = check_sphinx_version(ctx, sphinx_min_version) ctx.end_msg("yes (%s)" % ".".join(map(str, ver))) - ctx.start_msg("Checking Sphinx Verbose ") - if 'SPHINX_VERBOSE' not in ctx.env: - ctx.env.append_value('SPHINX_VERBOSE', ctx.options.sphinx_verbose) - level = sphinx_verbose(ctx) - if level == '-Q': - level = 'quiet' - ctx.end_msg(level) + ctx.start_msg("Checking Sphinx Options ") + if 'SPHINX_OPTIONS' not in ctx.env: + ctx.env.append_value('SPHINX_OPTIONS', ctx.options.sphinx_options) + opts = sphinx_options(ctx) + if len(opts) == 0: + opts = 'none' + ctx.end_msg(opts) + + ctx.start_msg("Checking Sphinx Nit-Pick mode ") + if ctx.options.sphinx_nit_pick: + opt = '-n' + msg = 'yes' + else: + opt = '-Q' + msg = 'no' + ctx.env.append_value('SPHINX_OPTIONS', opt) + ctx.end_msg(msg) + # # Check extensions. # @@ -428,10 +439,14 @@ def cmd_options(ctx): action = 'store_true', default = False, help = "Disable building with extra fonts for better quality (lower quality).") - ctx.add_option('--sphinx-verbose', + ctx.add_option('--sphinx-options', action = 'store', - default = "-Q", - help = "Sphinx verbose.") + default = "", + help = "Additional Sphinx options.") + ctx.add_option('--sphinx-nit-pick', + action = 'store_true', + default = False, + help = "Enable Sphinx nit-picky mode else be quiet") ctx.add_option('--pdf', action = 'store_true', default = False, |