mirror of
https://github.com/Fishwaldo/u-boot.git
synced 2025-03-18 21:21:37 +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)
|
tools.Run(*args)
|
||||||
return True
|
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
|
# pylint: disable=W0613
|
||||||
def fetch(self, method):
|
def fetch(self, method):
|
||||||
"""Fetch handler for a bintool
|
"""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,
|
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')
|
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(
|
subparsers.add_parser(
|
||||||
'entry-docs', help='Write out entry documentation (see entries.rst)')
|
'entry-docs', help='Write out entry documentation (see entries.rst)')
|
||||||
|
|
||||||
|
|
|
@ -140,7 +140,7 @@ def WriteEntryDocs(modules, test_missing=None):
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
modules: List of Module objects to get docs for
|
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
|
to show as missing even if it is present. Should be set to None in
|
||||||
normal use.
|
normal use.
|
||||||
"""
|
"""
|
||||||
|
@ -148,6 +148,18 @@ def WriteEntryDocs(modules, test_missing=None):
|
||||||
Entry.WriteDocs(modules, test_missing)
|
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):
|
def ListEntries(image_fname, entry_paths):
|
||||||
"""List the entries in an image
|
"""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')
|
comp_util.decompress(b'1234', 'invalid')
|
||||||
self.assertIn("Unknown algorithm 'invalid'", str(e.exception))
|
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__":
|
if __name__ == "__main__":
|
||||||
unittest.main()
|
unittest.main()
|
||||||
|
|
|
@ -35,6 +35,7 @@ sys.pycache_prefix = os.path.relpath(our_path, srctree)
|
||||||
# in PYTHONPATH)
|
# in PYTHONPATH)
|
||||||
sys.path.insert(2, our1_path)
|
sys.path.insert(2, our1_path)
|
||||||
|
|
||||||
|
from binman import bintool
|
||||||
from patman import test_util
|
from patman import test_util
|
||||||
|
|
||||||
# Bring in the libfdt module
|
# Bring in the libfdt module
|
||||||
|
@ -129,6 +130,9 @@ def RunBinman(args):
|
||||||
args.test_preserve_dirs, args.tests,
|
args.test_preserve_dirs, args.tests,
|
||||||
args.toolpath)
|
args.toolpath)
|
||||||
|
|
||||||
|
elif args.cmd == 'bintool-docs':
|
||||||
|
control.write_bintool_docs(bintool.Bintool.get_tool_list())
|
||||||
|
|
||||||
elif args.cmd == 'entry-docs':
|
elif args.cmd == 'entry-docs':
|
||||||
control.WriteEntryDocs(control.GetEntryModules())
|
control.WriteEntryDocs(control.GetEntryModules())
|
||||||
|
|
||||||
|
|
Loading…
Add table
Reference in a new issue