Development

Package layout

Location

Responsibility

src/gvu/api.py

Public sessions, models and dialogs

src/gvu/models.py

Workflow declarations, alignment, bounds, screens and result enums

src/gvu/menus.py

Native menu discovery, state and dispatch

src/gvu/controls.py

Native dialog-control descriptors and resolution

src/gvu/macos.py

Process-scoped macOS UI backend

src/gvu/viewer.py

Workflow validation and launch/reuse

src/gvu/surfaces.py

Live density-boundary ESP analysis

src/gvu/desktop.py

Display-independent placement calculations

src/gvu/logging.py

Structured events and logging configuration

tests/

Unit tests with temporary fixtures

docs/

Sphinx sources and Read the Docs theme configuration

Run scripts declare calculation-specific data and displays. Add reusable controls to the library rather than embedding another UI implementation in each run. Availability failures should be explicit; do not introduce silent fallbacks that claim an unsupported operation succeeded.

Build documentation

From the repository root:

uv sync --extra docs
uv run --extra docs sphinx-build -W --keep-going -b html docs docs/_build/html

Open docs/_build/html/index.html. The generated site includes:

  • Sidebar navigation and breadcrumbs.

  • Search and previous/next links.

  • A Python index and source views.

Generated HTML stays under the ignored _build directory; maintain the source pages and package docstrings.

The root .readthedocs.yaml configures Python, installation of the docs extra, the Sphinx configuration and warning-sensitive builds. A Read the Docs project can import this public repository to run those builds. GitHub Pages publishes the same Sphinx site through the documentation workflow.

Validate changes

uv run python -m unittest discover -s tests

After changing documentation or public API signatures:

  1. Build with warnings treated as errors.

  2. Review the API reference, menu tables, sidebar links and search output in the generated site.

  3. Test new native controls against the installed application using temporary fixtures. Close only the views those probes own.

  4. Keep the coverage record consistent with what was actually exercised.

Documentation sources

Publish a release

The publish.yml workflow uses PyPI Trusted Publishing with the GitHub environment pypi. Configure a pending publisher on PyPI with project gvu, owner ghovax, repository gvu, workflow publish.yml and environment pypi. This is required once, before the first upload; no long-lived API token is needed.

To prepare a release:

  1. Update the version in pyproject.toml and refresh uv.lock.

  2. Run the checks and build both distributions with uv build --no-sources.

  3. Create a tag matching the package version, for example v0.3.0.

  4. Push the tag to run the release workflow. It builds distributions, checks metadata, runs wheel/source-install smoke tests, generates attestations and performs the trusted upload.

A PyPI release version cannot be replaced; subsequent changes require a new version.

uv lock
uv run python -m unittest discover -s tests
uv build --no-sources
uv run twine check --strict dist/*
git tag v0.3.0
git push origin v0.3.0

The workflow_dispatch event can rerun a verified tag after correcting publishing authorization. The workflow checks the tag against package metadata before uploading.