mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-11-28 15:41:40 +00:00
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:
parent
a00d9713e4
commit
bc570646f6
5 changed files with 80 additions and 1 deletions
|
@ -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
|
||||
|
|
|
@ -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)')
|
||||
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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()
|
||||
|
|
|
@ -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())
|
||||
|
||||
|
|
Loading…
Reference in a new issue