Repository navigation
docs: migrate to zensical, with rendered screenshots and animations - #369
Open
tlambert03 wants to merge 11 commits into
Open
tlambert03 wants to merge 11 commits into
tlambert03 wants to merge 11 commits into
Conversation
… 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>
|
Docs preview: https://pyapp-kit.github.io/superqt/pr-preview/pr-369/ |
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 Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
this migrates the docs from mkdocs to zensical, and reworks most of the content.
The biggest change is the screenshots. Before,
show_widgetexec'd the first python block on each page at build time and saved one PNG. Now each example is a real file indocs/examples/, anddocs/_gen_media.pyruns it (once per theme, in a subprocess) and saves light and dark screenshots todocs/_generated/(gitignored, and cached by a hash of the example and the spec). Widgets with a scene indocs/_scenes.pyare 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 macosrenders native macOS widgets (see CONTRIBUTING.md).Other stuff:
show_memberslists the signals, enums, properties and methods, including documented Qt overrides)tests/test_docs.pychecks that every name in a public__all__has API docs, and is listed in the widgets or utilities indexdocs.ymlbuilds on every PR, and deploys togh-pagesfrom main (keeping thepr-preview/folder from ci: add a workflow to preview the docs on PRs #368)from superqt.fonticon import *, which raised because__all__listedQIconifyIconThe redirects in
zensical.tomlcover the two pages that moved (utilities/fonticonandutilities/iconify, now underutilities/icons/).