Skip to content

docs: migrate to zensical, with rendered screenshots and animations - #369

Open
tlambert03 wants to merge 11 commits into
pyapp-kit:mainfrom
tlambert03:new-docs
Open

tlambert03 wants to merge 11 commits into
pyapp-kit:mainfrom
tlambert03:new-docs

Conversation

@tlambert03

Copy link
Copy Markdown
Member

this migrates the docs from mkdocs to zensical, and reworks most of the content.

The biggest change is the screenshots. Before, show_widget exec'd the first python block on each page at build time and saved one PNG. Now each example is a real file in docs/examples/, and docs/_gen_media.py runs it (once per theme, in a subprocess) and saves light and dark screenshots to docs/_generated/ (gitignored, and cached by a hash of the example and the spec). Widgets with a scene in docs/_scenes.py are also recorded as animated webp: dragging the sliders, typing into the searchable widgets, picking a colormap, etc. CI renders offscreen with the fusion style; locally, --style macos renders native macOS widgets (see CONTRIBUTING.md).

Other stuff:

  • a new home page, with a gallery of widgets and utilities (the cards play their animation on hover)
  • the prose on every page got a review for accuracy, and each widget page has an API section (show_members lists the signals, enums, properties and methods, including documented Qt overrides)
  • an Icons section: a comparison of font icons and iconify, plus examples of colors, palettes and states
  • a live throttling/debouncing demo on the throttling page
  • tests/test_docs.py checks that every name in a public __all__ has API docs, and is listed in the widgets or utilities index
  • docs.yml builds on every PR, and deploys to gh-pages from main (keeping the pr-preview/ folder from ci: add a workflow to preview the docs on PRs #368)
  • fixes from superqt.fonticon import *, which raised because __all__ listed QIconifyIcon

The redirects in zensical.toml cover the two pages that moved (utilities/fonticon and utilities/iconify, now under utilities/icons/).

tlambert03 and others added 8 commits November 12, 2026 20:59
… animations

Replace mkdocs + mkdocs-material with zensical (native `zensical.toml`, modern
theme variant, light/dark palettes, navigation tabs and sections, instant
navigation and link previews).

Screenshots are no longer taken by a macro during the build (which exec'd the
first code block of each page). Instead, `docs/_gen_media.py` runs as a prepare
step before `zensical build`:

- the examples are real, runnable scripts in `docs/examples/`, included in the
  pages with snippets
- each one is rendered offscreen, once per theme, with Fusion and palettes that
  match the site, at 2x, in a subprocess per job (in parallel), and cached by
  content hash
- `docs/_scenes.py` scripts animations for widgets that benefit from them,
  driven with synthetic mouse and keyboard input, recorded as animated WebP
- pages show the light or dark variant to match the site's color scheme

The `show_members` macro now also finds signals inherited from superqt base
classes (with their comments as descriptions), separates properties, and
lists Qt methods that superqt reimplements and documents. The home page and
the widgets index are galleries of the rendered widgets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Renders the screenshots offscreen, builds with `zensical build --strict`, and
uploads the site as an artifact; pushes to main deploy it with ghp-import
(zensical has no `gh-deploy`).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Checked each page against the code, and rewrote it in plain language.

Fixed statements that were wrong:
- the labels of labeled sliders are line edits, not spin boxes
- the range slider's setter is `setBarVisible` (not `setBarIsVisible`), and
  the mouse wheel moves all of its handles (Alt spreads them)
- `ensure_main_thread` returns a `Future` (not `None`) unless `await_return`
- `QIconifyIcon` needs pyconify (the `iconify` extra)
- `QSearchableTreeWidget` filters on keys and values, not only keys
- `QColormapLineEdit()` doesn't make the colormap fill the combo box
  (`setFractionalColormapWidth(1)` does)
- unsupported `QQuantity` units raise `NotImplementedError`
- `QFlowLayout` is a layout, not a QWidget; PyQt5 support is 5.15

Filled in what was missing: installing a Qt binding and the optional extras,
pages for `QElidingLineEdit` and `qimage_to_array`, every public utility in
the utilities index, examples for throttling, signal blocking and font icon
animations, and descriptions of the options of each widget. Examples use
realistic text and values (e.g. a `QLargeIntSpinBox` value beyond 32 bits).

Also updated the setup instructions in CONTRIBUTING.md (uv, prek), and two
docstrings that rendered wrong in the API reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
It isn't defined there, so `from superqt.fonticon import *` raised an
AttributeError.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- home page: new SVG logo, a gallery of 12 widgets and 3 utilities; cards
  show a still, and play their animation while hovered
- widgets: a QColormapLineEdit page, sliders reordered, no edit button
- utilities: an Icons section (overview and comparison, QIconifyIcon,
  font icons), with examples of colors, palettes, and states; a live
  throttling/debouncing demo; API sections for the remaining public names
- media: native macOS rendering (`--style macos`), recorded clicks into
  popups and modal dialogs, seamless loops, and a shorter lead-in
- QIconifyIcon's docstring: the current number of icons and icon sets

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs.yml uploads the PR number with the site, and the new docs-preview.yml
(adapted from imaging-formats/yaozarrs#111) deploys it to
gh-pages/pr-preview/pr-N/ and comments the link.  The main deploy now
keeps pr-preview/ on the gh-pages branch, instead of force-pushing over it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Docs preview: https://pyapp-kit.github.io/superqt/pr-preview/pr-369/
Built from 491e7b9.

tlambert03 and others added 3 commits November 13, 2026 20:38
Each example gets the running app as `QApplication`, and `exec()` returns
at once.  Docs examples must show exactly one window (as the docs' renderer
expects), and the others at least one.  icon_explorer.py now raises a
clear error without a font pack (instead of an IndexError), so it's skipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- the macros' include_dir is now docs/_generated (no page uses includes):
  zensical watches it, so pages get the new sizes from manifest.json
  after a re-render, instead of needing `zensical build --clean`
- a missing screenshot raises in CI (`--strict` ignores macro warnings)
- drop `watch = ["src"]` (mkdocstrings' `paths` already watches it) and
  settings that only repeat zensical's defaults

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The site is built on macos-latest, and deployed from a separate (ubuntu)
job, which is the only one with write access.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.22%. Comparing base (51cb32e) to head (491e7b9).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #369      +/-   ##
==========================================
+ Coverage   85.05%   88.22%   +3.16%     
==========================================
  Files          49       49              
  Lines        3975     3975              
==========================================
+ Hits         3381     3507     +126     
+ Misses        594      468     -126     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This branch has not been deployed

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

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant