Changeset 62efd4c in rtems-docs

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.

Files:

• README.txt (modified) (3 diffs)
• common/waf.py (modified) (4 diffs)

README.txt

@@ -46 +46 @@
 
 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:
@@ -327 +339 @@
 
   $ ./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
@@ -342 +368 @@
   $ ./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:
-
-  $ ./waf configure --sphinx-verbose=-v
+verbose level:
+
+  $ ./waf configure --sphinx-options "-V -V"
   $ ./waf clean build
 

common/waf.py

@@ -28 +28 @@
         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
@@ -112 +112 @@
     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):
@@ -200 +200 @@
         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.
@@ -429 +440 @@
                    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',