[PATCH v2 3/8] waf: Change --sphinx-verbose to --sphinx-options, add --sphinx-nit-pick
chrisj at rtems.org
chrisj at rtems.org
Wed Feb 27 21:39:18 UTC 2019
From: Chris Johns <chrisj at rtems.org>
Provide options to manage sphinx. Make using the nit-picky mode simpler
to access.
---
README.txt | 44 ++++++++++++++++++++++++++++++++++++++++----
common/waf.py | 41 ++++++++++++++++++++++++++++-------------
2 files changed, 68 insertions(+), 17 deletions(-)
diff --git a/README.txt b/README.txt
index b1a5978..ed05fb8 100644
--- a/README.txt
+++ b/README.txt
@@ -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,
--
2.19.1
More information about the devel
mailing list