# 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`:

``` bash
uv run pytest
uv run ruff check src tests
uv run mypy src
```

The editor tests in `tests/test_editor_highlight.py` run the app and drive a headless browser with [Playwright](https://playwright.dev/python/). Install its Chromium once before the first run:

``` bash
uv run playwright install chromium
```

`pytest` 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()](../reference/editor_server.md#shypermaid.editor_server) and [viewer_server()](../reference/viewer_server.md#shypermaid.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:

``` bash
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.js
```

Then update the version table here and in `www/vendor/README.md`.

> **Warning: Warning**
>
> 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](https://posit-dev.github.io/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:

``` bash
uv sync --group docs
uv run great-docs build
uv run great-docs preview
```

The 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`.

> **Warning: Warning**
>
> 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`](https://mjfrigaard.github.io/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:

``` python
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.
