Skip to content

Libdoc: argument, return and raises documentation as tables - #5742

Open
Snooz82 wants to merge 14 commits into
robotframework:masterfrom
Snooz82:argument_doc_table_design
Open

Libdoc: argument, return and raises documentation as tables#5742
Snooz82 wants to merge 14 commits into
robotframework:masterfrom
Snooz82:argument_doc_table_design

Conversation

@Snooz82

@Snooz82 Snooz82 commented Aug 13, 2026

Copy link
Copy Markdown
Member

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

  • Arguments table: columns appear only when the keyword has that information. From 1280px the documentation sits next to the signature, below it otherwise. Long documentation is clamped to four lines with a more... button that opens the full
    text in a dialog.
  • Argument kinds are shown by a marker in front of the name (positional-only, named-only, *args, **kwargs), built into an SVG sprite at build time. Hovering or tapping a marker spells out what it means, in every supported language.
  • Returns and Raises are tables with a header, the documentation on the same line as the type.
  • Tables take the width their content needs; one that cannot shrink any further scrolls inside its own box rather than widening the card.
  • Mobile: one navigation bar with the keyword list and language menu, title shrinks when scrolled.
  • Accessibility: Lighthouse 0.59 → 0.98 (BuiltIn) and 0.51 → 0.96 (Browser) — contrast, heading order, landmarks, accessible names, target sizes, and zoom no longer blocked.
  • Large libraries: keywords outside the window are skipped while laying out, and the reading position survives a resize.
  • Pygments styles regenerated: default for light, monokai for dark.
  • Fix: the table of contents put nested lists next to their item instead of inside it, which is invalid HTML (src/robot/libdocpkg/htmlutils.py, acceptance test updated).

Testing — 437 Libdoc acceptance tests and the frontend unit test pass. Checked in Chrome, Firefox and Safari, and on a phone-sized viewport.

Copilot AI lite review requested due to automatic review settings August 13, 2026 12:41

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/web/libdoc/view.ts
Comment on lines 639 to 643
document.querySelectorAll(".tag-link").forEach((elem) => {
elem.addEventListener("click", (e) => {
this.tagSearch((e.target! as HTMLSpanElement).innerText);
});
});
Comment on lines +364 to +367
{{#each tags}}<span
class="tag-link"
title="{{t 'showTagKeywords'}}"
>{{this}}</span>{{/each}}
Comment on lines 446 to 452
.tag-link {
padding: 0.05rem 0.6rem;
font-size: var(--font-size-small);
border: 1px solid var(--border-color);
border-radius: 10px;
cursor: pointer;
}
Comment on lines +1 to +4
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";
Copilot AI review requested due to automatic review settings August 13, 2026 13:26

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. Use e.currentTarget (the .tag-link element) 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;

Copilot AI review requested due to automatic review settings August 13, 2026 17:29

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 (via initLanguageMenu), but the modal is not recreated if #modal-background already exists. That means the close button’s aria-label stays 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"));
    }

Copilot AI review requested due to automatic review settings August 13, 2026 19:16

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 from e.currentTarget (the .tag-link element) 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 if hideModal changes later.
  modalCloseButtonContainer.addEventListener("click", () => {
    hideModal();
  });

src/web/libdoc/view.ts:524

  • updateDocClamping() skips docs whose clientHeight is 0 ("not laid out yet"), leaving them permanently clamped and non-clickable. With content-visibility: auto on .keyword-container, most offscreen keyword docs start out unlaid-out and may never get a more... 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,
    }));

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants