Re: [igt-dev] [PATCH i-g-t 6/6] scripts/doc_to_xls.py: add an script to generate a doc spreadsheet

[Mauro Carvalho Chehab <mauro.chehab@linux.intel.com>]

On Fri, 26 May 2023 14:20:47 +0200
Kamil Konieczny <kamil.konieczny@linux.intel.com> wrote:

> Hi Mauro,
> 
> On 2023-05-22 at 16:22:01 +0200, Mauro Carvalho Chehab wrote:
> > From: Mauro Carvalho Chehab <mchehab@kernel.org>
> > 
> > Add a script to convert documentation to a spreadsheet.
> > 
> > The logic here can read multiple config files. It will retrieve
> > documentation from the files that are configured inside each input
> > JSON file.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>  
> 
> imho it is worth to add examples of useage here or as comments
> in source code.
> 
> Acked-by: Kamil Konieczny <kamil.konieczny@linux.intel.com>
> 
> Regards,
> Kamil

Good point. I'll add it to the script's help:

$ scripts/doc_to_xls.py --help
usage: doc_to_xls.py [-h] --config CONFIG [CONFIG ...] [--include-plan] --xls XLS

Write the contents of the testplan documentation to a XLS file.

options:
  -h, --help            show this help message and exit
  --config CONFIG [CONFIG ...]
                        JSON file describing the test plan template
  --include-plan        Include test plans, if any.
  --xls XLS             Output XLS file.

Examples:

1. Create a XLS file with a single worksheet with Xe driver documentation:

   scripts/doc_to_xls.py --config tests/kms_*json tests/*/*.json --xls igt_test_documentation.xls

2. Create a XLS file with one sheet per driver, for all drivers with testplan config files and KMS:

   scripts/doc_to_xls.py --config tests/kms_*json tests/*/*.json --xls igt_test_documentation.xls


I'll fold the enclosed diff at the patch and add your A-B.

Regards,
Mauro

---

diff --git a/scripts/doc_to_xls.py b/scripts/doc_to_xls.py
index 1f33c1828ceb..8531eeb81779 100755
--- a/scripts/doc_to_xls.py
+++ b/scripts/doc_to_xls.py
@@ -8,7 +8,19 @@
 ## Allow keeping inlined test documentation and validate   ##
 ## if the documentation is kept updated.                   ##
 
-"""Maintain test plan and test implementation documentation on IGT."""
+"""Write the contents of the testplan documentation to a XLS file."""
+
+EPILOG="""
+Examples:
+
+1. Create a XLS file with a single worksheet with Xe driver documentation:
+
+   scripts/doc_to_xls.py --config tests/kms_*json tests/*/*.json --xls igt_test_documentation.xls
+
+2. Create a XLS file with one sheet per driver, for all drivers with testplan config files and KMS:
+
+   scripts/doc_to_xls.py --config tests/kms_*json tests/*/*.json --xls igt_test_documentation.xls
+"""
 
 import argparse
 
@@ -16,9 +28,9 @@ from openpyxl import Workbook
 
 from test_list import TestList
 
-parser = argparse.ArgumentParser(description = "Print formatted kernel documentation to stdout.",
-                                 formatter_class = argparse.ArgumentDefaultsHelpFormatter,
-                                 epilog = 'If no action specified, assume --rest.')
+parser = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class = argparse.RawDescriptionHelpFormatter,
+                                 epilog = EPILOG)
 parser.add_argument("--config", required = True,  nargs='+',
                     help="JSON file describing the test plan template")
 parser.add_argument("--include-plan", action="store_true",