Render a protein structure as a self-contained static HTML file using Mol*, with residues colored, labeled, and styled from a CSV. Everything the view needs — coordinates, colors, tooltips, labels — is embedded in the one file, so it can be dropped on GitHub Pages with no backend.
- Documentation: https://jbloomlab.github.io/prot-struct-viz/
- Live example: https://jbloomlab.github.io/prot-struct-viz/examples/
pip install prot-struct-vizWrite a CSV of the residues you want to say something about, and a spec file naming the structure, where the HTML goes, and one or more views of it. Then:
prot-struct-viz spec.yamlThat writes the page, plus a report on any disagreement between the CSV and the structure. One spec can hold several named views — different colorings, labels, representations, or heteroatoms — and the page gets a selector that switches between them without moving the camera. The URL tracks the selector, so a link can point at one particular view.
The quick start shows both files in full; the documentation covers every spec key, the CSV columns, and what a reader of the output can click.
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,docs]"
scripts/check.sh # pytest + ruff + black
scripts/build_examples.sh # render examples/*/spec.yaml into examples/output/
scripts/build_docs.sh # mkdocs build --strictDocumentation lives in docs/, which is the single source — this README is a front door,
not a second copy. Conventions, and the checks to run after changing anything that affects
rendering, are in CLAUDE.md.
Releases are tag-driven and publish to PyPI through
trusted publishing, so no API token is
stored in the repo. The one-time PyPI setup and the per-release recipe are documented at
the top of .github/workflows/release.yml. In short:
# 1. Bump `version` in pyproject.toml and roll CHANGELOG's [Unreleased] into it.
git commit -am "release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tagsThe workflow verifies the tag matches pyproject.toml before anything reaches PyPI.