Development Guide¶

This guide covers how to set up the development environment for the PowerGenome tools web application.

Installation¶

Requirements¶

Python 3.8+
uv (recommended) or pip

Setup¶

Clone the repository:

git clone https://github.com/gschivley/PowerGenome-tools.git
cd PowerGenome-tools

Install dependencies using uv:

uv sync

Or install manually with pip:

pip install networkx scipy scikit-learn pandas pyyaml numpy
# Optional for map generation
pip install geopandas matplotlib

Web Application Development¶

The web application is located in the web/ directory. It uses PyScript to run Python code in the browser.

Running Locally¶

To test changes to the web app, you need to serve the web/ directory via HTTP.

Navigate to the web directory:
```
cd web
```
Start a simple Python server:
```
python -m http.server 8000
```
Open your browser to http://localhost:8000.

Key Files¶

web/index.html: The main HTML structure and UI.
web/cluster_app.py: The Python logic that runs in the browser (PyScript).
web/pyscript.toml: PyScript configuration and dependencies.

Playwright UI Tests¶

UI tests live in tests/ui. For wizard-step suites, prefer the shared-page pattern used in model-setup.spec.ts and new-resources.spec.ts: create one browser context and one booted page through the shared suite helper in tests/ui/fixtures/shared-app.ts. That helper loads the app once, verifies startup state, and runs the suite in serial mode. Reset app state in beforeEach with a page-object or test-only reset hook, as shown by model-setup.spec.ts and new-resources.spec.ts.

Keep smoke.spec.ts as true cold-start coverage. If a test is validating PyScript startup, page boot, or initial navigation, use Playwright's per-test page and call loadApp() inside the test instead of reusing a shared page.

Run the UI suite with:

npm run test:ui

Documentation¶

The documentation is built with MkDocs.

Building Docs¶

Install documentation dependencies:
```
uv sync --group dev
```
Serve the documentation locally:
```
uv run mkdocs serve
```
Build the static site:
```
uv run mkdocs build
```

Deployment¶

The documentation is deployed to GitHub Pages. The build process automatically includes the web/ application directory in the deployed site, ensuring the web app remains accessible at /web/.

To deploy manually:

uv run mkdocs gh-deploy