doc: add --no-index-modules option to genrest.py

This add a new option `--no-index-modules` which works similarly to
`--modules` but does not generated index pages, only retains the
tweaking of how paths are displayed on symbol information pages,
showing '<title>/path/within/module/Kconfig' for paths that fall
within modules.

This is required by NCS, where there are more "modules" which we don't
want to have indexes for.

Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
This commit is contained in:
Fabio Utzig 2020-06-04 09:35:54 -03:00 committed by Carles Cufí
commit 3f28f69477

View file

@ -89,6 +89,13 @@ def init():
# <path> is an absolute pathlib.Path instance, which is handy for robust
# path comparisons.
#
# no_index_modules:
# A list of (<title>, <path>) tuples. See the --no-index-modules flag.
# Empty if --no-index-modules wasn't passed.
#
# <path> is an absolute pathlib.Path instance, which is handy for robust
# path comparisons.
#
# separate_all_index:
# True if --separate-all-index was passed
#
@ -99,6 +106,7 @@ def init():
global out_dir
global index_desc
global modules
global no_index_modules
global separate_all_index
global strip_module_paths
@ -135,6 +143,25 @@ def init():
modules.append((title, suffix, abspath, desc_path))
no_index_modules = []
for module_spec in args.no_index_modules:
# Split on ',', but keep any ',,' as a literal ','. Temporarily
# represent a literal comma with null.
spec_parts = [part.replace("\0", ",")
for part in module_spec.replace(",,", "\0").split(",")]
if len(spec_parts) == 2:
title, path_s = spec_parts
else:
sys.exit(f"error: --no-index-modules argument '{module_spec}' "
"should have the format <title>,<path>.")
abspath = pathlib.Path(path_s).resolve()
if not abspath.is_dir():
sys.exit("error: path '{}' in --no-index-modules argument does not"
" exist".format(abspath))
no_index_modules.append((title, abspath))
def parse_args():
# Parses command-line arguments
@ -206,6 +233,26 @@ symbol information pages, showing
within modules. This behavior can be disabled by passing
--keep-module-paths.""")
parser.add_argument(
"--no-index-modules",
metavar="NO_INDEX_MODULE_SPECIFICATION",
nargs="+",
default=[],
help="""\
Passing --no-index-modules works similarly to --modules
but it does not generate index pages. It only tweaks how
paths are displayed on symbol information pages, showing
'<title>/path/within/module/Kconfig' for paths that fall
within modules. This behavior can be disabled by passing
--keep-module-paths.
Each NO_INDEX_MODULE_SPECIFICATION has the form
<title>,<path>
To insert a literal comma into any of the parts, double it,
e.g. 'My title,, with a comma'.""")
parser.add_argument(
"--separate-all-index",
action="store_true",
@ -764,6 +811,14 @@ def strip_module_path(path):
return f"<{title}>{os.path.sep}{relpath}"
for title, mod_path in no_index_modules:
try:
relpath = abspath.relative_to(mod_path)
except ValueError:
continue
return f"<{title}>{os.path.sep}{relpath}"
return path