Add scientific documentation and structure renderings

.github/workflows/ci.yml

@@ -22,10 +22,11 @@ jobs:
       - name: Build wheel
         run: |
           python -m pip install build
-          python -m build --wheel
-      - name: Check wheel
+          python -m build
+      - name: Check packages
         run: |
           wheel=$(find dist -name '*.whl' -print -quit)
+          sdist=$(find dist -name '*.tar.gz' -print -quit)
           python - "$wheel" <<'PY'
           import re
           import sys
@@ -45,13 +46,25 @@ jobs:
                           nested_file = f"pqviewer/static{nested}"
                           assert nested_file in files, f"missing {nested_file}"
           PY
+          tar -tzf "$sdist" | grep -q '/docs/conf.py$'
           python -m venv /tmp/pqviewer-smoke
           /tmp/pqviewer-smoke/bin/pip install "$wheel"
           cd /tmp
           /tmp/pqviewer-smoke/bin/pqviewer --help
           /tmp/pqviewer-smoke/bin/pqviewer render --help
           /tmp/pqviewer-smoke/bin/pqviewer-render --help
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install -e ".[docs]"
+      - run: python -m sphinx -W --keep-going -b html docs docs/_build/html
+
   frontend:
     runs-on: ubuntu-latest
     defaults:

.gitignore

@@ -12,3 +12,4 @@ output/
 .playwright-cli/
 frontend/node_modules/
 frontend/.vite/
+docs/_build/

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 PQViewer contributors
+Copyright (c) 2026 MolarVerse
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MANIFEST.in

@@ -2,10 +2,12 @@ include CHANGELOG.md
 include CITATION.cff
 include CODE_OF_CONDUCT.md
 include CONTRIBUTING.md
+include docs/conf.py
 include PRODUCT_DIRECTION.md
 include SECURITY.md
 include THIRD_PARTY_NOTICES.md
 include frontend/e2e/__screenshots__/darwin/acof-centered.png
 include frontend/public/pq-logo.png
-recursive-include docs *.md
+recursive-include docs *.md *.css *.png *.json *.pdb *.xyz *.extxyz
 recursive-include examples *.extxyz *.in *.md *.xyz
+prune docs/_build

README.md

@@ -12,7 +12,15 @@ reproducible publication figures in a modern browser interface.
 PQViewer is preparing for its first public beta. File and Python interfaces may
 still change before 1.0.
 
-![A triclinic framework in PQViewer](frontend/e2e/__screenshots__/darwin/acof-centered.png)
+![A 100-frame UMCM-9 trajectory in PQViewer](docs/assets/screenshots/trajectory-workspace.png)
+
+<p align="center">
+  <a href="docs/index.md"><strong>Explore the documentation</strong></a>
+</p>
+
+| Protein | Molecule | Framework |
+|:--:|:--:|:--:|
+| ![Crambin protein](docs/assets/renders/crambin.png) | ![C60 fullerene](docs/assets/renders/c60.png) | ![UMCM-9 MOF](docs/assets/renders/umcm-9.png) |
 
 ## Quick start
 
@@ -52,8 +60,8 @@ pqviewer optimization.traj
 - Opens structures, trajectories, PQ inputs, and joined restart runs.
 - Uses indexed access for PQ sources, ASE `.traj`, and indexed ASE sequences
   without retaining every coordinate frame in memory.
-- Displays forces, velocities, charges, periodic images, water, and ribbons
-  when the source provides them.
+- Displays forces, velocities, charges, periodic images, water, protein
+  cartoons, and crystal coordination polygons or polyhedra when supported.
 - Uses PQ's centered fractional cell convention, `[-0.5, 0.5)`, including
   triclinic cells.
 - Selects atoms by pointer, box, element, molecule, residue, connectivity, or
@@ -76,6 +84,7 @@ pqviewer examples/acof-triclinic.xyz
 
 ## Documentation
 
+- [Documentation overview](docs/index.md)
 - [Getting started](docs/getting-started.md)
 - [Viewer guide](docs/viewer-guide.md)
 - [Data sources and periodic conventions](docs/data-and-conventions.md)

THIRD_PARTY_NOTICES.md

@@ -3,7 +3,13 @@
 ## PQAnalysis example data
 
 `examples/acof-triclinic.xyz` contains the first four frames of the PQAnalysis
-`examples/traj2box/acof_triclinic.xyz` example.
+[`examples/traj2box/acof_triclinic.xyz`](https://github.com/MolarVerse/PQAnalysis/blob/main/examples/traj2box/acof_triclinic.xyz)
+example. The ACOF documentation render uses its first frame.
+
+The UMCM-9 documentation render and workspace screenshot use frame 1 of the
+100-frame PQAnalysis
+[`examples/traj2comtraj/umcm-9-md-01.xyz`](https://github.com/MolarVerse/PQAnalysis/blob/main/examples/traj2comtraj/umcm-9-md-01.xyz)
+trajectory.
 
 MIT License
 
@@ -26,3 +32,33 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+## Protein Data Bank entry 1CRN
+
+`docs/assets/sources/1CRN.pdb` and the corresponding render were produced from
+the Crambin structure in PDB entry
+[1CRN](https://www.rcsb.org/structure/1CRN). PDB archive data files are made
+available under the
+[CC0 1.0 dedication](https://www.rcsb.org/pages/policies). The structure should
+be cited as:
+
+> Hendrickson, W. A. & Teeter, M. M. Structure of the hydrophobic protein
+> crambin determined directly from the anomalous scattering of sulphur.
+> *Nature* **290**, 107–113 (1981).
+
+## Demonstration geometries
+
+The C60 fullerene, NaCl supercell, and illustrative water box shown in the
+documentation were generated with
+[ASE 3.29.0](https://wiki.fysik.dtu.dk/ase/) and rendered by PQViewer:
+
+- C60 uses `ase.build.molecule("C60")`.
+- NaCl uses `ase.build.bulk("NaCl", "rocksalt", a=5.64, cubic=True)` repeated
+  twice along each axis.
+- The water box places 27 `ase.build.molecule("H2O")` geometries on a
+  3 × 3 × 3 grid in a 12 Å cubic cell, with rotations from random seed 42.
+
+These are visual examples, not simulation results. Their exact geometries and
+portable PQViewer figure recipes are stored in `docs/assets/sources` and
+`docs/assets/recipes`. Each recipe reproduces a 2,400 × 1,800 px PNG at
+300 DPI.

docs/_static/custom.css

@@ -0,0 +1,71 @@
+:root {
+  --pst-color-primary: #1f718f;
+  --pst-color-secondary: #12313a;
+  --pst-color-link: #176c8c;
+  --pst-color-link-hover: #0d4e66;
+  --pst-font-family-base-system: Inter, ui-sans-serif, -apple-system,
+    BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --pst-font-family-monospace-system: "SFMono-Regular", Consolas,
+    "Liberation Mono", monospace;
+}
+
+html[data-theme="dark"] {
+  --pst-color-primary: #65bddb;
+  --pst-color-secondary: #94ccd9;
+  --pst-color-link: #65bddb;
+  --pst-color-link-hover: #9ed9eb;
+  --pst-color-background: #0d171b;
+  --pst-color-on-background: #e7eff0;
+  --pst-color-surface: #142228;
+}
+
+.bd-page-width {
+  max-width: 88rem;
+}
+
+.navbar-brand img {
+  width: 2rem;
+  height: 2rem;
+}
+
+.navbar-brand.logo .title {
+  font-weight: 700;
+  letter-spacing: -0.02em;
+}
+
+.bd-article h1,
+.bd-article h2,
+.bd-article h3 {
+  letter-spacing: -0.02em;
+}
+
+.pq-workspace {
+  margin: 1.5rem 0 0;
+}
+
+.pq-workspace img {
+  width: 100%;
+  border: 1px solid var(--pst-color-border);
+  border-radius: 0.35rem;
+}
+
+.sd-card {
+  box-shadow: none;
+}
+
+.sd-card-img-top {
+  aspect-ratio: 4 / 3;
+  border-bottom: 1px solid var(--pst-color-border);
+  background: var(--pst-color-surface);
+  object-fit: cover;
+}
+
+.sd-card:hover {
+  border-color: var(--pst-color-primary);
+}
+
+@media screen and (max-width: 67.99em) {
+  .bd-main .bd-content .bd-article-container {
+    max-width: 100%;
+  }
+}

docs/assets/recipes/c60.pqfigure.json

@@ -0,0 +1,119 @@
+{
+  "schema": "pqviewer.figure",
+  "schema_version": 1,
+  "source": {
+    "kind": "pq-trajectory",
+    "path": "../sources/c60.xyz",
+    "slice": {
+      "start": null,
+      "stop": null,
+      "step": null
+    },
+    "segments": [
+      {
+        "source_id": "../sources/c60.xyz",
+        "kind": "pq-trajectory",
+        "path": "../sources/c60.xyz",
+        "input": null,
+        "frame_count": 1,
+        "files": {
+          "trajectory": "../sources/c60.xyz"
+        }
+      }
+    ]
+  },
+  "frame": {
+    "index": 0,
+    "fingerprint": "frame-v1:00686f5c04542925",
+    "key": {
+      "source_id": "../sources/c60.xyz",
+      "source_index": 0,
+      "segment_index": 0,
+      "step": null,
+      "time": null,
+      "time_unit": null
+    }
+  },
+  "scene": {
+    "presentation": {
+      "mode": "licorice",
+      "water": "show",
+      "hydrogens": true,
+      "wrap": "none",
+      "cellOrigin": [
+        0,
+        0,
+        0
+      ],
+      "mirror": [
+        false,
+        false,
+        false
+      ],
+      "images": {
+        "min": [
+          0,
+          0,
+          0
+        ],
+        "max": [
+          0,
+          0,
+          0
+        ]
+      },
+      "cell": false,
+      "forces": false,
+      "velocities": false,
+      "atomScale": 1.15,
+      "bondScale": 1.15,
+      "color": "element",
+      "quality": "high"
+    },
+    "selection": {
+      "atoms": [],
+      "intent": "measurement",
+      "minimumImage": false
+    },
+    "vectors": {
+      "forceScale": 1,
+      "velocityScale": 1
+    }
+  },
+  "camera": {
+    "position": [
+      8,
+      5,
+      10
+    ],
+    "target": [
+      0,
+      0,
+      0
+    ],
+    "up": [
+      0,
+      1,
+      0
+    ],
+    "fov": 34,
+    "zoom": 1,
+    "near": 0.02,
+    "far": 5000
+  },
+  "output": {
+    "format": "png",
+    "width": 2400,
+    "height": 1800,
+    "dpi": 300,
+    "background": {
+      "kind": "solid",
+      "color": "#f5f8f8"
+    },
+    "projection": "orthographic",
+    "fit": true,
+    "padding": 0.1,
+    "periodicContext": true
+  },
+  "annotations": []
+}