doc: genrest: Use a separate index page for all symbols

Add an option --separate-all-index that makes genrest.py generate a
separate index-all.rst index page that lists all symbols, instead of
listing all symbols in index.rst. index-all.rst is linked from
index.rst.

This was originally motivated by an external project where index.rst
becomes the top-level page, which runs into a Sphinx bottleneck with
sphinx_rtd_theme. See https://github.com/sphinx-doc/sphinx/issues/6909.

This turned out pretty nice after some feedback from Ruth Fuchss, so use
it for Zephyr too.

Also unclutter the generated documentation a bit by removing some
headings. This makes the navigation menu on the left nicer too.

Piggyback making genrest.py executable, which is handy when running it
manually.

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This commit is contained in:
Ulf Magnusson 2019-12-10 15:11:01 +01:00 committed by Maureen Helm
commit 5c28f39e7f
2 changed files with 58 additions and 19 deletions

View file

@ -206,6 +206,7 @@ add_custom_target(
KCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE}
KCONFIG_DOC_MODE=1
${PYTHON_EXECUTABLE} scripts/genrest.py ${RST_OUT}/doc/reference/kconfig/
--separate-all-index
--keep-module-paths
--modules Architecture,arch,${ZEPHYR_BASE}/arch
Driver,drivers,${ZEPHYR_BASE}/drivers

76
doc/scripts/genrest.py Normal file → Executable file
View file

@ -1,3 +1,5 @@
#!/usr/bin/env python3
"""
Generates an alphabetical index of Kconfig symbols with links in index.rst, and
a separate CONFIG_FOO.rst file for each Kconfig symbol.
@ -88,6 +90,9 @@ def init():
# <path> is an absolute pathlib.Path instance, which is handy for robust
# path comparisons.
#
# separate_all_index:
# True if --separate-all-index was passed
#
# strip_module_paths:
# True unless --keep-module-paths was passed
@ -95,6 +100,7 @@ def init():
global out_dir
global index_desc
global modules
global separate_all_index
global strip_module_paths
args = parse_args()
@ -102,6 +108,7 @@ def init():
kconf = kconfiglib.Kconfig(args.kconfig)
out_dir = args.out_dir
index_desc = args.index_desc
separate_all_index = args.separate_all_index
strip_module_paths = args.strip_module_paths
modules = []
@ -180,16 +187,17 @@ deep). The title of the index is "<title> Configuration
Options", and a 'configuration_options_<suffix>' RST link
target is inserted at the top of the index page.
If <index description path> is given, it should be the
path to an RST file. The contents of this file will appear
under the Overview heading on the symbol index page for the
module. If no <index description path> is given, a generic
description is used instead.
If <index description path> is given, it should be the path
to an RST file. The contents of this file will appear under
at the top of the symbol index page for the module,
underneath the heading. If no <index description path> is
given, a generic description is used instead.
The top-level index.rst index page contains a TOC tree that
links to the index-*.rst pages for any modules. It also
includes a list of all symbols, including symbols that do
not appear in any module.
not appear in any module. Pass --separate-all-index to use a
separate index for the list of all symbols.
If a symbol is defined in more than one module, it will be
listed on several index pages.
@ -200,6 +208,23 @@ symbol information pages, showing
within modules. This behavior can be disabled by passing
--keep-module-paths.""")
parser.add_argument(
"--separate-all-index",
action="store_true",
help="""\
Instead of listing all symbols in index.rst, use a separate
index-all.rst index page, which is linked from index.rst.
Probably only useful in combination with --modules.
index-all.rst has a 'configuration_options_all' RST link
target.
This option can make the documentation build orders of
magnitude faster when the index.rst generated by this script
is the top-level page, because Sphinx currently runs into a
bottleneck with large top-level pages with some themes. See
https://github.com/sphinx-doc/sphinx/issues/6909.""")
parser.add_argument(
"--keep-module-paths",
dest="strip_module_paths",
@ -227,28 +252,44 @@ def write_index_pages():
def write_main_index_page():
# Writes the main index page, which lists all symbols. In --modules mode,
# links to the module index pages are included.
# links to the module index pages are included. If --separate-all-index was
# passed, a separate index-all.rst index is generated as well.
rst = index_header(title="Configuration Options",
link="configuration_options",
desc_path=index_desc)
if separate_all_index:
rst += """
This index page lists all symbols, regardless of where they are defined:
.. toctree::
:maxdepth: 1
index-all.rst\
"""
write_if_updated("index-all.rst",
index_header(title="All Configuration Options",
link="configuration_options_all",
desc_path=None) +
sym_table_rst("Configuration Options",
kconf.unique_defined_syms))
if modules:
rst += """
Subsystems
**********
These index pages list symbols defined within a particular subsystem, while the
list below includes all configuration symbols.
These index pages only list symbols defined within a particular subsystem:
.. toctree::
:maxdepth: 1
""" + "\n".join(" index-" + suffix for _, suffix, _, _, in modules)
rst += sym_table_rst("All configuration options",
kconf.unique_defined_syms)
if not separate_all_index:
# Put index of all symbols in index.rst
rst += sym_table_rst("All configuration options",
kconf.unique_defined_syms)
write_if_updated("index.rst", rst)
@ -332,8 +373,8 @@ def index_header(title, link, desc_path):
# Link target string
#
# desc_path:
# Path to file with RST file put into the Overview section at the
# beginning of the page. If None, a generic description is used.
# Path to file with RST to put at the of the page, underneath the
# heading. If None, a generic description is used.
if desc_path is None:
desc = DEFAULT_INDEX_DESC
@ -351,9 +392,6 @@ def index_header(title, link, desc_path):
{}
{}
Overview
********
{}
This documentation is generated automatically from the :file:`Kconfig` files by