[PATCH rtems-docs] Add option --build-manuals to build multiple specific manuals.

[Gedare Bloom]

Hi Shashvat,

On Fri, Feb 11, 2022 at 1:38 AM Shashvat <shashvatjain2002 at gmail.com> wrote:
>
> Hello all!!
> This patch adds the --build-manuals option enabling one to build specific
> documentation manuals. I also updated the README.
>

Is there a ticket associated with this, or any feature request? Or
just something you thought of doing?

> ---
>  README.txt | 10 +++++++---
>  common/waf.py | 9 +++++++++
>  wscript | 9 +++++++++
>  3 files changed, 25 insertions(+), 3 deletions(-)
>
> diff --git a/README.txt b/README.txt
> index 828c9e7..8480b0c 100644
> --- a/README.txt
> +++ b/README.txt
> @@ -407,7 +407,9 @@ To build enter in the top directory:
>                      [--sphinx-nit-pick] \
>                      [--plantuml] \
>                      [--ditaa] \
> - [--disable-extra-fonts]
> + [--disable-extra-fonts] \
> + [--build-manuals]
> +
I don't think an extra blank line is needed here.

>
>    $ ./waf
>
> @@ -448,8 +450,10 @@ verbose level:
>    $ ./waf configure --sphinx-options "-V -V"
>    $ ./waf clean build
>
> -You can enter a manual's directory and run the same configure command and
> build
> -just that manual.
> +If you wish to build only some specific manuals,
> +use the '--build-manuals=<manual-name-1>,<manual-name-2>' option with
> +configure to build only those specific manuals.
> +
>
>  Documentation Standard
>  ----------------------
> diff --git a/common/waf.py b/common/waf.py
> index fa9aecb..e6ae059 100644
> --- a/common/waf.py
> +++ b/common/waf.py
> @@ -240,6 +240,11 @@ def cmd_configure(ctx):
>          check_sphinx_extension(ctx, 'sphinxcontrib.bibtex')
>
>      #
> + # Build specific manuals.
This spacing looks wrong.

> + #
> + if ctx.options.build_manuals!="":
Follow the coding style of the surrounding text. For Python code, we
generally follow
https://docs.rtems.org/branches/master/eng/python-devel.html

> + ctx.env.MANUALS = ctx.options.build_manuals.split(',')
Probably want a blank line here. None of the other options take
multiple values. I wonder if there is any value to having a multiple
option here, versus building just one manual selectively? You could
still have an 'all' option as the default. That will reduce the
complexity of the command line argument processing.

> + #
This spacing looks wrong.

>      # Optional builds.
>      #
>      ctx.env.BUILD_PDF = 'no'
> @@ -480,6 +485,10 @@ def cmd_options(ctx):
>                     action = 'store',
>                     default = "",
>                     help = "Additional Sphinx options.")
> + ctx.add_option('--build-manuals',
> + action = 'store',
> + default = '',
I guess by default this will not build any manuals? The principle of
least surprise suggests that by default the behavior should be what it
used to be if you omit the argument, so build everything. otherwise,
you break existing workflows and scripts.

> + help = "Build specific manuals. To build multiple manuals use ','
> delimeter.")
>      ctx.add_option('--sphinx-nit-pick',
>                     action = 'store_true',
>                     default = False,
> diff --git a/wscript b/wscript
> index fd8f10c..a887a95 100644
> --- a/wscript
> +++ b/wscript
> @@ -96,6 +96,15 @@ def build(ctx):
>      #
>      ctx.recurse('images')
>      ctx.add_group('images')
> +
> + #
> + # Overwrite to new building list, if env.MANUALS is created during
> configuration.
> + #
> + if ctx.env.MANUALS:
> + building = ctx.env.MANUALS
This is not good python, no indent after 'if', so there's nothing in
the conditional code block, you just always set building to
ctx.env.MANUALS.

> + print("Building the following manuals:-")
> + for manual in building:
> + print(manual)
missing indent here too. But the print statements seem to be
inconsistent with other printed output for this code. You generally
want to keep that consistent.

>
>      for b in building:
>          ctx.recurse(b)
>
> --
> 2.33.0
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel