Re: [PATCH 3/3] doc: rewrite shell scripts in Python

[Bruce Richardson <bruce.richardson@intel.com>]

On Fri, Apr 01, 2022 at 12:28:30AM +0300, Dmitry Kozlyuk wrote:
> Shell used in documentation generation could not run on Windows.
> Rewrite scripts in Python.
> New scripts use proper path separators and handle paths with spaces.
> 
> Signed-off-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
> ---

Generally looks ok to me, couple of minor comments inline below.

Reviewed-by: Bruce Richardson <bruce.richardson@intel.com>

>  doc/api/generate_doxygen.py  | 19 +++++++++++++++++++
>  doc/api/generate_doxygen.sh  | 12 ------------
>  doc/api/generate_examples.py | 31 +++++++++++++++++++++++++++++++
>  doc/api/generate_examples.sh | 20 --------------------
>  doc/api/meson.build          |  6 +++---
>  5 files changed, 53 insertions(+), 35 deletions(-)
>  create mode 100644 doc/api/generate_doxygen.py
>  delete mode 100755 doc/api/generate_doxygen.sh
>  create mode 100644 doc/api/generate_examples.py
>  delete mode 100755 doc/api/generate_examples.sh
> 
<snip>

> diff --git a/doc/api/generate_examples.py b/doc/api/generate_examples.py
> new file mode 100644
> index 0000000000..66933f9472
> --- /dev/null
> +++ b/doc/api/generate_examples.py
> @@ -0,0 +1,31 @@
> +#!/usr/bin/env python3
> +# SPDX-License-Identifier: BSD-3-Clause
> +# (c) 2018 Luca Boccassi <bluca@debian.org>
> +# (c) 2022 Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
> +
> +import os, sys
> +
> +examples_dir, api_examples = sys.argv[1:]
> +
> +sources = []
> +with open(f'{api_examples}.d', 'w') as dep:
> +    print(f'{api_examples}:', end=' ', file=dep)
> +    for root, _, files in os.walk(examples_dir):
> +        for name in files:
> +            is_source = name.endswith('.c')
> +            if is_source or name == 'meson.meson.build':

duplicate "meson."

> +                path = os.path.join(root, name)
> +                if is_source:
> +                    sources.append(path)
> +                print(path , end=' ', file=dep)
> +
> +sys.stdout = open(api_examples, 'w')

While this is a literal translation of what is done in the .sh file, I
wonder if, for consistency, in the python versions we should always either
use stdout redirection or always use "file=" option to printing. Right now
we have a mix of both.

> +print('/**')
> +print('@page examples DPDK Example Programs')
> +print()

Is this additional print done deliberately for clarity vs just putting '\n'
on previous line?

> +for path in sources:
> +    # Produce consistent output with forward slashes on all systems.
> +    # Every \ in paths within examples directory is a separator, not escape.
> +    relpath = os.path.relpath(path, examples_dir).replace('\\', '/')
> +    print(f'@example examples/{relpath}')
> +print('*/')