Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
name: Docs

on:
push:
branches: [main]
pull_request:
workflow_dispatch:

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
build:
# screenshots are rendered with the native macOS style (in real windows)
runs-on: macos-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0

- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
python-version: "3.13"
enable-cache: true
cache-dependency-glob: "**/pyproject.toml"

- name: Render screenshots and animations
run: uv run --group docs python docs/_gen_media.py --style macos

- name: Build
run: |
uv run --group docs zensical build --clean --strict
touch site/.nojekyll

# for docs-preview.yml, which deploys PR builds (it can't see the PR number)
- if: github.event_name == 'pull_request'
run: echo "${{ github.event.number }}" > pr-number

- uses: actions/upload-artifact@v7
with:
name: site
path: |
site
pr-number
include-hidden-files: true # (.nojekyll)

# zensical has no gh-deploy; push the built site to the gh-pages branch
# (keeping the PR previews, which docs-preview.yml puts in pr-preview/)
deploy:
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v7
- uses: actions/download-artifact@v8
with:
name: site
- uses: JamesIves/github-pages-deploy-action@v4
with:
folder: site
clean-exclude: pr-preview/
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -81,5 +81,5 @@ src/superqt/_version.py
screenshots

.mypy_cache
docs/_auto_images/
docs/_generated/
uv.lock
42 changes: 35 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,22 @@ To get started fork this repository, and clone your fork:
git clone https://github.com/<your_organization>/superqt
cd superqt

# install in editable mode (this will install PyQt6 as the Qt backend)
pip install -e .[dev]
# create an environment with the dev dependencies, and PyQt6 as the Qt backend
uv sync --extra pyqt6

# install pre-commit hooks
pre-commit install
# install the pre-commit hooks
uv run prek install

# run tests & make sure everything is working!
pytest
uv run pytest
```

## Targeted platforms

All widgets must be well-tested, and should work on:

- Python 3.11 and above
- PyQt5 (5.11 and above) & PyQt6
- PyQt5 (5.15) & PyQt6
- PySide6
- macOS, Windows, & Linux

Expand All @@ -48,4 +48,32 @@ All widgets should try to match the native Qt API as much as possible:

## Testing

Tests can be run in the current environment with `pytest`.
Tests can be run in the current environment with `uv run pytest`.

## Documentation

The documentation is built with [Zensical](https://zensical.org). Widget
screenshots and animations are rendered from the runnable scripts in
`docs/examples/` in a separate step, before building (outputs are cached, so
reruns only render what changed):

```bash
uv run --group docs python docs/_gen_media.py # renders into docs/_generated/
uv run --group docs zensical serve # preview at http://localhost:8000
```

By default, widgets are drawn offscreen with Qt's Fusion style. On macOS,
`--style macos` draws them with the native macOS style instead; this opens the
windows on screen while they're rendered, one at a time (so it takes a few
minutes), and they shouldn't be clicked or typed into until it's done. The
published docs are rendered this way, on a macOS runner in CI.

To document a new widget:

1. Add a runnable example, `docs/examples/<name>.py`, that shows one window.
2. Add a page, `docs/widgets/<name>.md`, that shows the example with
`{{ show_widget() }}`, includes its code with a (block-style) snippet in a
`python` code block, and lists its API with
`{{ show_members("superqt.<Class>") }}` (see the other pages). Add the page
to `nav` in `zensical.toml`, and a `card` for it in `docs/widgets/index.md`.
3. Optionally, set the window size or record an animation in `docs/_scenes.py`.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Components are tested on:

- macOS, Windows, & Linux
- Python 3.11 and above
- PyQt5 (5.11 and above) & PyQt6
- PyQt5 (5.15) & PyQt6
- PySide6

## Documentation
Expand Down
20 changes: 20 additions & 0 deletions docs/_gen_media.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
"""Render the widget screenshots and animations used in the docs.

Each `docs/examples/<name>.py` is run offscreen, once per theme (light and dark),
and the window it shows is saved to `docs/_generated/<name>-<theme>.png`. Examples
with a scene in `docs/_scenes.py` are also recorded as `<name>-<theme>.webp`
(animated). Outputs are cached by content hash, so unchanged examples are skipped.

uv run --group docs python docs/_gen_media.py # everything
uv run --group docs python docs/_gen_media.py qcollapsible --force
uv run --group docs python docs/_gen_media.py --style macos # native, on macOS
"""

import sys
from pathlib import Path

if __name__ == "__main__":
sys.path.insert(0, str(Path(__file__).parent))
from _media import main

sys.exit(main(description=__doc__.splitlines()[0]))
Loading
Loading