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>
This commit is contained in:
Simon Glass 2022-01-09 20:14:11 -07:00
parent a00d9713e4
commit bc570646f6
5 changed files with 80 additions and 1 deletions

View file

@ -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

View file

@ -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)')

View file

@ -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

View file

@ -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()

View file

@ -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())