Checks and Docs
This page lists the commands that check the package and build this site. Run the checks before each commit.
Run the checks
The tests, linter, and type checker come from the dev dependency group, which uv sync installs by default. Run them through uv:
uv run pytest
uv run ruff check src tests
uv run mypy srcThe editor tests in tests/test_editor_highlight.py run the app and drive a headless browser with Playwright. Install its Chromium once before the first run:
uv run playwright install chromiumpytest prints a coverage table after the tests. The browser tests run the app in a separate process, so they don’t count toward coverage. The server tests in tests/test_modules_server.py do count: they run editor_server() and viewer_server() in memory with shiny.testserver.test_server() and record the render messages the viewer sends. mypy runs in strict mode, so every function in src/ needs type hints.
Update the vendored libraries
The app serves its JavaScript libraries from src/shypermaid/www/vendor/ instead of a CDN, so it runs offline and inside a desktop app:
| File | Package | Version |
|---|---|---|
mermaid.min.js |
mermaid |
12.3.0 |
svg-pan-zoom.min.js |
svg-pan-zoom |
3.6.2 |
To change a version, edit it in the commands below, download the files again, and run the tests:
V=src/shypermaid/www/vendor
NPM=https://cdn.jsdelivr.net/npm
curl -fsSL -o $V/mermaid.min.js $NPM/mermaid@12.3.0/dist/mermaid.min.js
curl -fsSL -o $V/svg-pan-zoom.min.js $NPM/svg-pan-zoom@3.6.2/dist/svg-pan-zoom.min.jsThen update the version table here and in www/vendor/README.md.
Since Mermaid 12, mermaid.min.js includes the ELK layout, so the app no longer vendors @mermaid-js/layout-elk. Do not go back to a Mermaid 11 release without restoring that plugin; tests/test_layout.py fails if ELK stops drawing. Mermaid 12 needs ES2024 browsers (Safari 17.4 or later).
Build the docs
The site is built with great-docs, which lives in the docs dependency group (Python 3.11 or later). The settings live in great-docs.yml, and the guide pages live in user_guide/. Install the group, build the site, then preview it in a browser:
uv sync --group docs
uv run great-docs build
uv run great-docs previewThe reference pages come from the numpy style docstrings in src/shypermaid/. A new public function needs a docstring and an entry in the reference section of great-docs.yml.
Diagrams on these pages must use a {mermaid} cell, not a plain mermaid fence. A plain fence builds with no warning but shows the Mermaid source as text.
The call trees on the Package Layout and Render Cycle pages are {python} cells that run callgrove on every build. callgrove is in the docs group (installed from GitHub), so a changed call shows up in the next build with no manual step. Run the same calls in a console to check a refactor before you push:
from callgrove import call_tree_dir
call_tree_dir("src/shypermaid", root="create_app")The build writes to great-docs/, which is listed in .gitignore.
A push to main runs .github/workflows/docs.yml, which builds the site and publishes it to GitHub Pages.