A navigation sidebar for the HTML manuals#174
Conversation
lancesix
left a comment
lancesix
left a comment
There was a problem hiding this comment.
I only did a very brief read through, and 😍 !
Thank for doing this.
Just a simple question, and overall, given that we only ship GDB (+ coremerge) and do not ship LD / GAS / ..., do we need to theme those?
| @@ -0,0 +1,388 @@ | |||
| /* Copyright (C) 2026 Free Software Foundation, Inc. | |||
There was a problem hiding this comment.
I have not tested, but is such header correclty detected by LibreJS?
The HTML build of the manual emits one bare page per node, with only the texinfo prev/next/up links to get around. This commit adds a navigation tree sidebar that stays visible on the left of every page. texinfo has no built-in support for a sidebar, but it can be driven through a texi2any init file, which is enough to build one ourselves, which we do here with CSS and JavaScript. The original motivation was GDB's manual, but the feature works with any texinfo manual in the tree, thus its implementation files are put in the texinfo/toc-sidebar/ directory. There's a README file in there with some high level information and pointers that you can follow to see how this all works. This patch wires the sidebar for GDB's manual, both as example, and as main motivation for the feature. GDB's Makefile also gains a MANUAL_CSS hook: a list of extra stylesheets, empty by default, each referenced with --css-ref and copied in to the manual's output directory. This can be used to theme/brand the manual without editing the sources. Change-Id: I488990a9d2863d1a96fa34a4656e58b976d96f4a
The sidebar tree can be large, so finding a section by name means scrolling and expanding nodes by hand. This adds a filter box at the top of the sidebar that narrows the tree as you type. This matches on section titles only, not on the body text of the manual. The box is part of the static sidebar shell. toc-sidebar.js watches it and, for each keystroke, marks the entries whose titles contain the text along with the chain of ancestors that leads to them. A CSS class on the tree then hides everything unmarked and forces the kept branches open, so the path to each match stays visible. The matches themselves are shown in bold. Clearing the box, or pressing Escape, drops the filtering class and the normal tree comes back, with current page and expand/collapse state intact. Change-Id: I06a066e7b0a9fc55bdb4d156be733705a9e287ce
The sidebar currently has a fixed width. Add a draggable divider between the sidebar and the content. Change-Id: Ia72edf9fc2e8e66d341fb36b6d0ed5397b51d6a9
This commit wires the ld HTML manual up to TOC sidebar feature, and adds support for MANUAL_CSS theming. Change-Id: I957a6987989481e6f83a40d9bcf17227bd6412c0
This commit wires the gas HTML manual up to TOC sidebar feature, and adds support for MANUAL_CSS theming. Change-Id: I70991592ade11649aa8046540927cee796e82ece
This commit wires the binutils HTML manual up to TOC sidebar feature, and adds support for MANUAL_CSS theming. Change-Id: Ifad2a083cb3890654c2da49eaf0b8bd9d765c7bc
This commit wires the bfd HTML manual up to TOC sidebar feature, and adds support for MANUAL_CSS theming. Change-Id: Ia7c6ea242291ef6c6fa5b24144dcd26e19a6689a
The sidebar feature stylesheet (toc-sidebar.css) reads its style values (colors and layout metrics) from --toc-sidebar-* custom properties, and ships a neutral default theme that sets them, so the manual is fully styled on its own. A separate theme stylesheet can override those properties to restyle the manual. This adds such a theme for the ROCgdb manual, which is published on the AMD ROCm documentation site, so the manual matches the surrounding pages. rocm-theme.css sets the palette and the manual's general look: the body and heading type, the code styling, headings, links, the per-node nav panel, and tables. It is currently plugged into the manual's MANUAL_CSS make variable in the Makefile directly for simplicity, though it could instead be passed down at build time by passing MANUAL_CSS to make. The values are not invented. The ROCm site is built with the pydata-sphinx-theme, with some ROCm overrides. The script rocm-theme-sync.py, added by this commit too, fetches the live ROCm site's CSS, extracts the relevant source variables, and rewrites the generated :root block of rocm-theme.css in place. Not every metric the theme matches is a --pst-* custom property. pydata keeps some relevant properties in its rule bodies rather than in custom properties, so rocm-theme-sync.py cannot pull them. Those are transcribed by hand and noted as such in the stylesheet. This is a downstream-only patch. Change-Id: Ia096b4d64c702f97a8ed3ae1bdeedbf5aa45bb48
This adds ROCm theming to the LD manual, via hardcoded MANUAL_CSS. Change-Id: I337f9aa72846e304bbf89ca29adeed4aa55e5b94
This adds ROCm theming to the GAS manual, via hardcoded MANUAL_CSS. Change-Id: I1985a88dfe67c3382d3c34421a2454c36279242d
This adds ROCm theming to the binutils manual, via hardcoded MANUAL_CSS. Change-Id: Ie43e1ba47b154a29e75022cc07aed53ea3119063
This adds ROCm theming to the bfd manual, via hardcoded MANUAL_CSS. Change-Id: I437dcfe41392398c84baa478cdae216b7ada8210
palves
force-pushed
the
users/palves/toc-sidebar
branch
from
ed5fdee to
22ac872
Compare
|
Added notes about texinfo API and HTML stability, after digging through the texinfo sources and NEWS in some more detail. gnu.org seems to be down a lot nowadays... https://gnu.googlesource.com/texinfo seems to be the next best thing. |
The current docs generation process does generate the html of all of those, e.g., https://rocm.docs.amd.com/projects/ROCgdb/en/latest/ROCgdb/ld/doc/ld/index.html . There are some xrefs into binutils in the gdb manual, but now that I check, they link to sourceware.org. Do we have a link to the coremerge docs in the gdb manual? I couldn't find it. If we do, it'd make sense to carry the binutils docs too. Otherwise, probably not. The non-gdb manuals we host may be unreachable, but not 100% sure. In any case, at first, I made this work for GDB (and used gdb-prefixed symbols in the css, javascript, etc, which was a pain to generalize later :-P) , and the new files all lived inside the gdb/doc/ dir. Then I realized that none of what I had was GDB-specific and should work with any texinfo manual, so I tried wiring it into the ld, gas, etc manuals . Also, keeping the idea of upstreaming all this except the rocm theme, I thought I'd try to see how hard it'd be to have a single MANUAL_CSS Makefile variable that works on all manuals in the tree. If people like that, I should explore making sure the top level Makefile passes down MANUAL_CSS to the submakes, and then we wouldn't have to hack in the rocm-theme.css file in each of the tool's makefiles, and if we wanted, in none, we could pass MANUAL_CSS at build time. So that's mainly why I did that. Just to see that is all worked, and to decide whether this would be a GDB-only thing, or for all the manuals in the tree. |
3 participants
The HTML build of texinfo manuals emits one bare page per node, with
only the texinfo prev/next/up links to get around. For ROCgdb, we
want something closer to a modern documentation site: a navigation
tree that stays visible on the left of every page.
Unfortunately, texinfo has no built-in support for a sidebar, but OTOH
fortunately it can be driven by a texi2any init file, which is enough
to build a sidebar ourselves, with custom CSS and JavaScript. The
init file we're adding uses a texi2any init API introduced in version
7.0, and falls back to the default contents-only manual on older
texi2any. The texinfo version that comes with Ubuntu 22.04 is too old
(6.8), but the version in Ubuntu 24.04 (7.1) is good.
This series adds the sidebar, built from the manual's own table of
contents so there is no separate data to keep in sync. The sidebar
needs JavaScript, and with JavaScript off the page falls back to the
plain single-column layout the manual had before. The sidebar
remembers its position and set of open nodes across page navigation.
On top of the base sidebar, the series adds a filter box that narrows
the tree as you type, and a draggable divider to customize the sidebar
width.
One of the new files is a Perl file, but that's not by choice. The
sidebar is driven by a new texi2any init file, toc-sidebar.init.
texi2any is itself a Perl program and loads its --init-file into its
own interpreter, so the init file has to be Perl. This is the same
way texinfo's own bundled HTML customization is done.
The series targets the split HTML build (one page per node), which is
what the AMD documentation site publishes. The single-page manual
(makeinfo --no-split, the gdb.html linked from
https://sourceware.org/gdb/documentation/) is built separately and
does not use the init file, so it stays as it is today. The sidebar's
design assumes per-page navigation and does not carry over to a single
page -- that mode would require a different (and probably simpler)
implementation.
The sidebar comes with a theme/style that works well with the default
texinfo style.
For ROCgdb, we'd like to use the same theme used by the rest of the
ROCm documentation website. For that, the sidebar is theme aware, and
the series also adds support for theming, via a MANUAL_CSS Makefile
variable. For the theme/stylesheet to use, the series adds a
rocm-theme.css file that mimics the ROCm documentation website's
style. Part of it was automatically generated by a new
rocm-theme-sync.py script, also included in the series.
Preview URLs
No sidebar (as currently)
https://palves.github.io/gdb-manual-preview/toc-pane/bare/gdb/
https://palves.github.io/gdb-manual-preview/toc-pane/bare/binutils/
https://palves.github.io/gdb-manual-preview/toc-pane/bare/gas/
https://palves.github.io/gdb-manual-preview/toc-pane/bare/ld/
https://palves.github.io/gdb-manual-preview/toc-pane/bare/bfd/
Sidebar + default theme
https://palves.github.io/gdb-manual-preview/toc-pane/default/gdb/
https://palves.github.io/gdb-manual-preview/toc-pane/default/binutils/
https://palves.github.io/gdb-manual-preview/toc-pane/default/gas/
https://palves.github.io/gdb-manual-preview/toc-pane/default/ld/
https://palves.github.io/gdb-manual-preview/toc-pane/default/bfd/
Sidebar + ROCm theme
https://palves.github.io/gdb-manual-preview/toc-pane/rocm/gdb/
https://palves.github.io/gdb-manual-preview/toc-pane/rocm/binutils/
https://palves.github.io/gdb-manual-preview/toc-pane/rocm/gas/
https://palves.github.io/gdb-manual-preview/toc-pane/rocm/ld/
https://palves.github.io/gdb-manual-preview/toc-pane/rocm/bfd/