- {"".join(next_level)}
- {"".join(items)}
'
f'
'
)
- # we don't want to generate the "Title of Contents" header for sections,
- # docbook didn't and it's only distracting clutter unless it's the main table.
- # we also want to generate tocs only for a top-level section (ie, one that is
- # not itself contained in another section)
- print_title = toc.kind != 'section'
- if toc.kind == 'section':
- if toc.parent and toc.parent.kind == 'section':
- toc_depth = 0
- else:
- toc_depth = self._html_params.section_toc_depth
- elif toc.starts_new_chunk and toc.kind != 'book':
- toc_depth = self._html_params.chunk_toc_depth
- else:
- toc_depth = self._html_params.toc_depth
- if not (items := walk_and_emit(toc, toc_depth)):
- return ""
- figures = build_list("Figures", "list-of-figures", toc.figures)
- examples = build_list("Examples", "list-of-examples", toc.examples)
- return "".join([
- f'List of {kind}
' - f'- {"".join(entries)}
- {entries}
',
- '
'
- f'{figures}'
- f'{examples}'
- ])
+ nav = render_entries(root.children, self._html_params.sidebar_depth)
+ figures = build_list("Figures", "list-of-figures", root.figures)
+ examples = build_list("Examples", "list-of-examples", root.examples)
+ return f'{nav}{figures}{examples}'
def _make_hN(self, level: int) -> tuple[str, str]:
- # for some reason chapters didn't increase the hN nesting count in docbook xslts.
- # originally this was duplicated here for consistency with docbook rendering, but
- # it could be reevaluated and changed now that docbook is gone.
- if self._toplevel_tag == 'chapter':
- level -= 1
- # this style setting is also for docbook compatibility only and could well go away.
- style = ""
- if level + self._hlevel_offset < 3 \
- and (self._toplevel_tag == 'section' or (self._toplevel_tag == 'chapter' and level > 0)):
- style = "clear: both"
- tag, hstyle = super()._make_hN(max(1, level))
- return tag, style
+ # book heading := h1
+ # Everything else is h2 ... h6
+ return super()._make_hN(level + 1)
def _included_thing(self, tag: str, token: Token, tokens: Sequence[Token], i: int) -> str:
outer, inner = [], []
- # since books have no non-include content the toplevel book wrapper will not count
- # towards nesting depth. other types will have at least a title+id heading which
- # *does* count towards the nesting depth. chapters give a -1 to included sections
- # mirroring the special handing in _make_hN. sigh.
- hoffset = (
- 0 if not self._headings
- else self._headings[-1].level - 1 if self._toplevel_tag == 'chapter'
- else self._headings[-1].level
- )
outer.append(self._maybe_close_partintro())
into = token.meta['include-args'].get('into-file')
fragments = token.meta['included']
- state = self._push(tag, hoffset)
+ state = self._push(tag)
if into:
toc = TocEntry.of(fragments[0][0][0])
- inner.append(self._file_header(toc))
- # we do not set _hlevel_offset=0 because docbook didn't either.
+ # chunk pages carry the same whole-book sidebar as the main page.
+ inner.append(self._file_header(toc, sidebar=self._build_sidebar(toc)))
else:
inner = outer
in_dir = self._in_dir
@@ -755,21 +737,36 @@ class HTMLConverter(BaseConverter[ManualHTMLRenderer]):
server_redirects_file.write("\n".join(formatted_server_redirects))
+class _DeprecatedDepthFlag(argparse.Action):
+ def __call__(self, parser: argparse.ArgumentParser, namespace: argparse.Namespace,
+ values: Any, option_string: str | None = None) -> None:
+ parser.error(f"{option_string} has been removed, use --sidebar-depth instead")
+
def _build_cli_html(p: argparse.ArgumentParser) -> None:
p.add_argument('--manpage-urls', required=True)
p.add_argument('--revision', required=True)
p.add_argument('--generator', default='nixos-render-docs')
p.add_argument('--stylesheet', default=[], action='append')
p.add_argument('--script', default=[], action='append')
- p.add_argument('--toc-depth', default=1, type=int)
- p.add_argument('--chunk-toc-depth', default=1, type=int)
- p.add_argument('--section-toc-depth', default=0, type=int)
p.add_argument('--media-dir', default="media", type=Path)
p.add_argument('--redirects', type=Path)
+ p.add_argument('--sidebar-depth', default=2, type=int)
+ # nav metadata (JSON): {"open": ["anchor-id", ...]} selects which sidebar
+ # entries render expanded; omitted or absent means everything is collapsed.
+ p.add_argument('--nav', type=Path)
+ # Deprecated flags,
+ p.add_argument('--toc-depth', nargs='?', action=_DeprecatedDepthFlag, default=None)
+ p.add_argument('--chunk-toc-depth', nargs='?', action=_DeprecatedDepthFlag, default=None)
+ p.add_argument('--section-toc-depth', nargs='?', action=_DeprecatedDepthFlag, default=None)
+ # Positional
p.add_argument('infile', type=Path)
p.add_argument('outfile', type=Path)
def _run_cli_html(args: argparse.Namespace) -> None:
+ sidebar_open: frozenset[str] = frozenset()
+ if args.nav:
+ with open(args.nav) as nav_file:
+ sidebar_open = frozenset(json.load(nav_file).get("open", []))
with open(args.manpage_urls) as manpage_urls, open(Path(__file__).parent / "redirects.js") as redirects_script:
redirects = None
if args.redirects:
@@ -778,8 +775,8 @@ def _run_cli_html(args: argparse.Namespace) -> None:
md = HTMLConverter(
args.revision,
- HTMLParameters(args.generator, args.stylesheet, args.script, args.toc_depth,
- args.chunk_toc_depth, args.section_toc_depth, args.media_dir),
+ HTMLParameters(args.generator, args.stylesheet, args.script,
+ args.sidebar_depth, args.media_dir, sidebar_open),
json.load(manpage_urls), redirects)
md.convert(args.infile, args.outfile)
diff --git a/pkgs/by-name/ni/nixos-render-docs/src/tests/test_auto_id_prefix.py b/pkgs/by-name/ni/nixos-render-docs/src/tests/test_auto_id_prefix.py
index 6fb706bad5ac..fce017fc70ba 100644
--- a/pkgs/by-name/ni/nixos-render-docs/src/tests/test_auto_id_prefix.py
+++ b/pkgs/by-name/ni/nixos-render-docs/src/tests/test_auto_id_prefix.py
@@ -10,7 +10,7 @@ def set_prefix(token: Token, ident: str) -> None:
def test_auto_id_prefix_simple() -> None:
- md = HTMLConverter("1.0.0", HTMLParameters("", [], [], 2, 2, 2, Path("")), {})
+ md = HTMLConverter("1.0.0", HTMLParameters("", [], [], 2, Path("")), {})
src = f"""
# title
@@ -31,7 +31,7 @@ def test_auto_id_prefix_simple() -> None:
def test_auto_id_prefix_repeated() -> None:
- md = HTMLConverter("1.0.0", HTMLParameters("", [], [], 2, 2, 2, Path("")), {})
+ md = HTMLConverter("1.0.0", HTMLParameters("", [], [], 2, Path("")), {})
src = f"""
# title
@@ -57,7 +57,7 @@ def test_auto_id_prefix_repeated() -> None:
]
def test_auto_id_prefix_maximum_nested() -> None:
- md = HTMLConverter("1.0.0", HTMLParameters("", [], [], 2, 2, 2, Path("")), {})
+ md = HTMLConverter("1.0.0", HTMLParameters("", [], [], 2, Path("")), {})
src = f"""
# h1
diff --git a/pkgs/by-name/ni/nixos-render-docs/src/tests/test_manual.py b/pkgs/by-name/ni/nixos-render-docs/src/tests/test_manual.py
new file mode 100644
index 000000000000..14f7024ce186
--- /dev/null
+++ b/pkgs/by-name/ni/nixos-render-docs/src/tests/test_manual.py
@@ -0,0 +1,124 @@
+from pathlib import Path
+
+from nixos_render_docs.manual import HTMLConverter, HTMLParameters
+
+
+def _build(tmp_path: Path, sidebar_depth: int = 2, sidebar_open: frozenset[str] = frozenset()) -> str:
+ (tmp_path / "part.md").write_text(
+ "# Build helpers {#part-builders}\n\n" # -> h2
+ "```{=include=} chapters\nchapter.md\n```\n"
+ )
+ (tmp_path / "chapter.md").write_text(
+ "# Fixed-point arguments {#chap-fpa}\n\n" # -> h2
+ "Intro.\n\n"
+ "## First section {#sec-first}\n\n" # -> h3
+ "Body.\n\n"
+ "### A subsection {#sub-a}\n\n"
+ "Deep.\n\n"
+ "#### Deeper {#d4}\n\n"
+ "More.\n\n"
+ "##### Deepest {#d5}\n\n"
+ "Most.\n"
+ )
+ (tmp_path / "index.md").write_text(
+ "# Test manual {#book-test}\n\n" # -> h1 (book title)
+ "## Version 1\n\n" # -> h2
+ "```{=include=} parts\npart.md\n```\n"
+ )
+ out = tmp_path / "out"
+ out.mkdir(exist_ok=True)
+ conv = HTMLConverter(
+ "1.0.0",
+ HTMLParameters("test-gen", [], [], sidebar_depth, Path("media"), sidebar_open),
+ {},
+ )
+ conv.convert(tmp_path / "index.md", out / "index.html")
+ return (out / "index.html").read_text()
+
+
+def test_single_h1_and_flat_heading_levels(tmp_path: Path) -> None:
+ html = _build(tmp_path)
+ # There should be only one h1 on an html for acessibility and semantic reasons
+ assert html.count("Table of Contents
' if print_title else "", - f'- '
- f' {"".join(items)}'
- f'