Libdoc: argument, return and raises documentation as tables - #5742
Libdoc: argument, return and raises documentation as tables#5742Snooz82 wants to merge 14 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
This PR modernizes the Libdoc HTML frontend to present keyword Arguments, Returns, and Raises as responsive tables (instead of signature + separate doc blocks), adds argument-kind markers via an SVG sprite, and improves navigation, performance on large libraries, and accessibility-related styling/structure.
Changes:
- Render Arguments/Returns/Raises as tables with responsive column behavior, clamped per-argument docs, and a modal for expanded documentation.
- Add build-time inlined SVG sprite icons for argument kinds (positional-only, named-only, *args, **kwargs) with localized explanations.
- Improve layout/navigation (single top bar on mobile, title resizing on scroll), performance (content-visibility and scroll-anchor restoration), and regenerate Pygments styles.
Reviewed changes
Copilot reviewed 11 out of 17 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| src/web/package.json | Adds Parcel inline-string transformer dependency used by bundle-text: imports. |
| src/web/package-lock.json | Lockfile updates for the new Parcel transformer and transitive dependency reshaping. |
| src/web/libdoc/view.ts | Implements doc clamping + modal, resize/scroll handling, and argument-kind helpers/icons integration. |
| src/web/libdoc/styles/pygments.css | Replaces old generated styles with updated light/dark palettes keyed off data-theme. |
| src/web/libdoc/styles/main.css | Major layout/table styling updates, responsive nav/title behavior, and table scrolling behavior. |
| src/web/libdoc/styles/doc_formatting.css | Adjusts doc typography/spacing and code block styling using new CSS variables. |
| src/web/libdoc/modal.ts | Improves modal structure and accessibility (aria-label for icon-only close button). |
| src/web/libdoc/libdoc.html | Converts keyword sections to table-based rendering and updates semantic structure (e.g., <main>). |
| src/web/libdoc/icons/varargs.svg | New icon asset for varargs marker. |
| src/web/libdoc/icons/pos-only.svg | New icon asset for positional-only marker. |
| src/web/libdoc/icons/named-only.svg | New icon asset for named-only marker. |
| src/web/libdoc/icons/kwargs.svg | New icon asset for kwargs marker. |
| src/web/libdoc/icons/icons.ts | Builds and injects the SVG sprite from inlined SVG sources. |
| src/web/libdoc/i18n/translations.json | Adds new localized strings for table UI, markers, and modal interactions. |
| src/robot/libdocpkg/htmlutils.py | Fixes invalid nested TOC list HTML generation by nesting <ul> inside its <li>. |
| atest/robot/libdoc/toc.robot | Updates acceptance expectations for corrected TOC HTML nesting. |
Files not reviewed (1)
- src/web/package-lock.json: Generated file
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| document.querySelectorAll(".tag-link").forEach((elem) => { | ||
| elem.addEventListener("click", (e) => { | ||
| this.tagSearch((e.target! as HTMLSpanElement).innerText); | ||
| }); | ||
| }); |
| {{#each tags}}<span | ||
| class="tag-link" | ||
| title="{{t 'showTagKeywords'}}" | ||
| >{{this}}</span>{{/each}} |
| .tag-link { | ||
| padding: 0.05rem 0.6rem; | ||
| font-size: var(--font-size-small); | ||
| border: 1px solid var(--border-color); | ||
| border-radius: 10px; | ||
| cursor: pointer; | ||
| } |
| import kwargs from "bundle-text:./kwargs.svg"; | ||
| import namedOnly from "bundle-text:./named-only.svg"; | ||
| import posOnly from "bundle-text:./pos-only.svg"; | ||
| import varargs from "bundle-text:./varargs.svg"; |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 17 changed files in this pull request and generated no new comments.
Files not reviewed (1)
- src/web/package-lock.json: Generated file
Suppressed comments (2)
src/web/libdoc/view.ts:642
- The tag click handler reads the tag text from
e.target. When the tag text is highlighted (mark.js wraps matches in ), clicks can target the element and only pass the substring instead of the full tag, causing incorrect tag filtering. Usee.currentTarget(the.tag-linkelement) instead.
document.querySelectorAll(".tag-link").forEach((elem) => {
elem.addEventListener("click", (e) => {
this.tagSearch((e.target! as HTMLSpanElement).innerText);
});
src/web/libdoc/view.ts:547
- The clamped doc click handler runs for clicks on links inside the documentation. That can cause conflicting behavior (e.g., clicking a type link can both open the type modal and also open the arg-doc modal, resulting in multiple modal contents being appended). Skip opening the arg-doc modal when the click originates from an element.
This issue also appears on line 639 of the same file.
const showDetails = (event: Event) => {
event.stopPropagation();
this.showArgDocModal(wrap);
};
doc.onclick = showDetails;
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 17 changed files in this pull request and generated no new comments.
Files not reviewed (1)
- src/web/package-lock.json: Generated file
Suppressed comments (1)
src/web/libdoc/view.ts:218
- When switching the UI language,
render()is called again (viainitLanguageMenu), but the modal is not recreated if#modal-backgroundalready exists. That means the close button’saria-labelstays in the original language, which is an accessibility regression for screen readers after language changes. Update the existing close button label on every render (or recreate the modal) so it always matches the current translation.
if (!document.getElementById("modal-background")) {
createModal(this.translations.translate("closeDialog"));
}
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 17 changed files in this pull request and generated no new comments.
Files not reviewed (1)
- src/web/package-lock.json: Generated file
Suppressed comments (4)
src/web/libdoc/view.ts:642
- The tag click handler reads the tag name from
e.target.innerText, which can be only the highlighted substring when mark.js wraps part of the tag (e.g. searching "foo" highlights foobar). Clicking then filters by a partial tag and produces the wrong results. Read frome.currentTarget(the.tag-linkelement) and trim it instead.
document.querySelectorAll(".tag-link").forEach((elem) => {
elem.addEventListener("click", (e) => {
this.tagSearch((e.target! as HTMLSpanElement).innerText);
});
src/web/libdoc/libdoc.html:367
- Tags are interactive (they register a click handler in
view.ts) but are rendered as<span>elements, which are not focusable or keyboard-activatable by default. Using a<button type="button">here provides correct semantics and keyboard support (Enter/Space) without extra JS.
{{#each tags}}<span
class="tag-link"
title="{{t 'showTagKeywords'}}"
>{{this}}</span>{{/each}}
src/web/libdoc/modal.ts:32
- The close action is wired both on the button and on its container, so clicking the close button triggers
hideModal()twice (including scheduling duplicate timeouts to clear the content). Remove one of the listeners to avoid redundant work and potential double side effects ifhideModalchanges later.
modalCloseButtonContainer.addEventListener("click", () => {
hideModal();
});
src/web/libdoc/view.ts:524
updateDocClamping()skips docs whoseclientHeightis 0 ("not laid out yet"), leaving them permanently clamped and non-clickable. Withcontent-visibility: autoon.keyword-container, most offscreen keyword docs start out unlaid-out and may never get amore...button when they later enter the viewport.
// Hidden documentation -- filtered out by the search, not laid out yet --
// measures zero and would look like it fits. It stays clamped, which is
// how the template renders it anyway.
const measured = docs.map((doc) => ({
known: doc.clientHeight > 0,
overflowing: doc.scrollHeight > doc.clientHeight + 1,
}));
Keyword arguments now render as a table with a column per fact — name, type, default, documentation — instead of a signature line with the documentation below it. Returns and Raises use the same table, with TYPE and, when there is one,
DOCUMENTATION. This makes the per-argument documentation from the Arguments: docstring sections visible where it belongs.
Changes
text in a dialog.
Testing — 437 Libdoc acceptance tests and the frontend unit test pass. Checked in Chrome, Firefox and Safari, and on a phone-sized viewport.