[PATCH v2 36/38] binman: Add a command to generate bintool docs

[Simon Glass]

Each bintool has some documentation which can be useful for the user.
Add a new command that collects this and writes it into a .rst file.

Signed-off-by: Simon Glass <sjg at chromium.org>
---

(no changes since v1)

 tools/binman/bintool.py | 45 +++++++++++++++++++++++++++++++++++++++++
 tools/binman/cmdline.py |  3 +++
 tools/binman/control.py | 14 ++++++++++++-
 tools/binman/ftest.py   | 15 ++++++++++++++
 tools/binman/main.py    |  4 ++++
 5 files changed, 80 insertions(+), 1 deletion(-)

diff --git a/tools/binman/bintool.py b/tools/binman/bintool.py
index 34102dafa2a..e2e5660d167 100644
--- a/tools/binman/bintool.py
+++ b/tools/binman/bintool.py
@@ -387,6 +387,51 @@ class Bintool:
         tools.Run(*args)
         return True
 
+    @staticmethod
+    def WriteDocs(modules, test_missing=None):
+        """Write out documentation about the various bintools to stdout
+
+        Args:
+            modules: List of modules to include
+            test_missing: Used for testing. This is a module to report
+                as missing
+        """
+        print('''.. SPDX-License-Identifier: GPL-2.0+
+
+Binman bintool Documentation
+============================
+
+This file describes the bintools (binary tools) supported by binman. Bintools
+are binman's name for external executables that it runs to generate or process
+binaries. It is fairly easy to create new bintools. Just add a new file to the
+'btool' directory. You can use existing bintools as examples.
+
+
+''')
+        modules = sorted(modules)
+        missing = []
+        for name in modules:
+            module = Bintool.find_bintool_class(name)
+            docs = getattr(module, '__doc__')
+            if test_missing == name:
+                docs = None
+            if docs:
+                lines = docs.splitlines()
+                first_line = lines[0]
+                rest = [line[4:] for line in lines[1:]]
+                hdr = 'Bintool: %s: %s' % (name, first_line)
+                print(hdr)
+                print('-' * len(hdr))
+                print('\n'.join(rest))
+                print()
+                print()
+            else:
+                missing.append(name)
+
+        if missing:
+            raise ValueError('Documentation is missing for modules: %s' %
+                             ', '.join(missing))
+
     # pylint: disable=W0613
     def fetch(self, method):
         """Fetch handler for a bintool
diff --git a/tools/binman/cmdline.py b/tools/binman/cmdline.py
index 5ccb2383885..0626b850f48 100644
--- a/tools/binman/cmdline.py
+++ b/tools/binman/cmdline.py
@@ -129,6 +129,9 @@ controlled by a description in the board device tree.'''
     build_parser.add_argument('--update-fdt-in-elf', type=str,
         help='Update an ELF file with the output dtb: infile,outfile,begin_sym,end_sym')
 
+    subparsers.add_parser(
+        'bintool-docs', help='Write out bintool documentation (see bintool.rst)')
+
     subparsers.add_parser(
         'entry-docs', help='Write out entry documentation (see entries.rst)')
 
diff --git a/tools/binman/control.py b/tools/binman/control.py
index bbd7773c314..2daad05b804 100644
--- a/tools/binman/control.py
+++ b/tools/binman/control.py
@@ -140,7 +140,7 @@ def WriteEntryDocs(modules, test_missing=None):
 
     Args:
         modules: List of Module objects to get docs for
-        test_missing: Used for testing only, to force an entry's documeentation
+        test_missing: Used for testing only, to force an entry's documentation
             to show as missing even if it is present. Should be set to None in
             normal use.
     """
@@ -148,6 +148,18 @@ def WriteEntryDocs(modules, test_missing=None):
     Entry.WriteDocs(modules, test_missing)
 
 
+def write_bintool_docs(modules, test_missing=None):
+    """Write out documentation for all bintools
+
+    Args:
+        modules: List of Module objects to get docs for
+        test_missing: Used for testing only, to force an entry's documentation
+            to show as missing even if it is present. Should be set to None in
+            normal use.
+    """
+    bintool.Bintool.WriteDocs(modules, test_missing)
+
+
 def ListEntries(image_fname, entry_paths):
     """List the entries in an image
 
diff --git a/tools/binman/ftest.py b/tools/binman/ftest.py
index a3454ddb104..ca200ae9f8f 100644
--- a/tools/binman/ftest.py
+++ b/tools/binman/ftest.py
@@ -5085,6 +5085,21 @@ fdt         fdtmap                Extract the devicetree blob from the fdtmap
             comp_util.decompress(b'1234', 'invalid')
         self.assertIn("Unknown algorithm 'invalid'", str(e.exception))
 
+    def testBintoolDocs(self):
+        """Test for creation of bintool documentation"""
+        with test_util.capture_sys_output() as (stdout, stderr):
+            control.write_bintool_docs(control.bintool.Bintool.get_tool_list())
+        self.assertTrue(len(stdout.getvalue()) > 0)
+
+    def testBintoolDocsMissing(self):
+        """Test handling of missing bintool documentation"""
+        with self.assertRaises(ValueError) as e:
+            with test_util.capture_sys_output() as (stdout, stderr):
+                control.write_bintool_docs(
+                    control.bintool.Bintool.get_tool_list(), 'mkimage')
+        self.assertIn('Documentation is missing for modules: mkimage',
+                      str(e.exception))
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/tools/binman/main.py b/tools/binman/main.py
index dcf20290f2b..03462e7bb8b 100755
--- a/tools/binman/main.py
+++ b/tools/binman/main.py
@@ -35,6 +35,7 @@ sys.pycache_prefix = os.path.relpath(our_path, srctree)
 # in PYTHONPATH)
 sys.path.insert(2, our1_path)
 
+from binman import bintool
 from patman import test_util
 
 # Bring in the libfdt module
@@ -129,6 +130,9 @@ def RunBinman(args):
                                 args.test_preserve_dirs, args.tests,
                                 args.toolpath)
 
+    elif args.cmd == 'bintool-docs':
+        control.write_bintool_docs(bintool.Bintool.get_tool_list())
+
     elif args.cmd == 'entry-docs':
         control.WriteEntryDocs(control.GetEntryModules())
 
-- 
2.34.1.575.g55b058a8bb-goog