binman: Add a command to generate bintool docs

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@chromium.org>

diff --git a/tools/binman/bintool.py b/tools/binman/bintool.py
index 34102dafa2a84b716648a5f66369fb074550375f..e2e5660d1676c189b3c7e11bf1a21c10e914e9bf 100644 (file)
--- 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 5ccb23838850688c740f8ba94a3c84bb2dfbff21..0626b850f487d292a96c97f0d4479b3e1cc5df71 100644 (file)
--- 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 bbd7773c31404d3767b079ae5149d0b6227c7504..2daad05b804108402c594a0a5a81c3e0f32d053c 100644 (file)
--- 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 a3454ddb1041f5193264ada0b2f05ca3a8cd1853..ca200ae9f8f9910431f6ddb3fa2acf3873836e78 100644 (file)
--- 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 dcf20290f2b9b2c08aee3627d5e7453ac1ecff00..03462e7bb8b102a7505b00f45999e6493741a29f 100755 (executable)
--- 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())