Add PQSetup documentation site

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install the package and docs dependencies
+        run: python -m pip install -e ".[docs]"
+      - name: Build the documentation
+        run: python -m sphinx -W --keep-going -b html docs docs/_build/html
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/_build/html
+
+  deploy-docs:
+    needs: build-docs
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -10,6 +10,7 @@ htmlcov/
 build/
 dist/
 output/
+docs/_build/
 .playwright-cli/
 frontend/node_modules/
 frontend/.vite/

README.md

@@ -1,98 +1,108 @@
 <img src="https://raw.githubusercontent.com/MolarVerse/PQSetup/main/frontend/public/pq-logo.png" alt="PQSetup logo" width="200">
 
-<h1 align="center">PQSetup</h1>
+[![CI](https://github.com/MolarVerse/PQSetup/actions/workflows/ci.yml/badge.svg)](https://github.com/MolarVerse/PQSetup/actions/workflows/ci.yml)
+[![Docs](https://github.com/MolarVerse/PQSetup/actions/workflows/docs.yml/badge.svg)](https://molarverse.github.io/PQSetup/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-<p align="center">
-  Prepare and validate PQ simulation inputs before a run.
-</p>
+# PQSetup
 
-<p align="center">
-  <a href="https://github.com/MolarVerse/PQSetup/actions/workflows/ci.yml"><img src="https://github.com/MolarVerse/PQSetup/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+">
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2f6f8f.svg" alt="MIT License"></a>
-</p>
+Prepare and validate PQ simulation inputs in a local browser interface.
 
-PQSetup is a local graphical setup tool for
-[PQ](https://github.com/MolarVerse/PQ). It checks structures, guides ensemble
-and method selection, builds equilibration and sampling plans, and exports
-readable inputs with a fail-fast run script.
+## Install
 
-![PQSetup structure and preflight workflow](docs/assets/pqsetup-workspace.png)
-
-## Quick start
-
-PQSetup requires Python 3.11 or newer. A PQ installation is recommended but
-not required to prepare an input.
+PQSetup is currently installed from source and requires Python 3.11 or newer.
 
 ```bash
 git clone https://github.com/MolarVerse/PQSetup.git
 cd PQSetup
 python3 -m venv .venv
 source .venv/bin/activate
 python -m pip install .
-pqsetup
 ```
 
-The interface is bundled with the Python package, so Node.js is not needed to
-install or run PQSetup. It opens on `127.0.0.1` and does not submit or run a
-simulation.
+The interface is included in the Python package. Node.js is not required.
 
-Check the local PQ installation and available external calculators:
+## Quick Start
+
+Open the graphical interface:
+
+```bash
+pqsetup
+```
+
+Inspect the selected PQ executable and available calculators:
 
 ```bash
 pqsetup doctor
 ```
 
-For an executable with a different name or location:
+Use a PQ executable with a different name or location:
 
 ```bash
-pqsetup --pq-executable /path/to/PQ
+pqsetup --pq-executable /path/to/PQ doctor
 ```
 
-The same path can be set with `PQ_EXECUTABLE`.
+Validate an existing input:
 
-## PQ compatibility
+```bash
+pqsetup validate run.in
+```
 
-PQSetup currently targets the stable PQ v0.6.4 input schema. It detects the
-selected executable's version and uses PQ's machine-readable CLI when
-available:
+See the [documentation](https://molarverse.github.io/PQSetup/) for server
+options, validation scopes, and complete setup examples.
 
-| PQ command | Used for |
+## Input
+
+| Structure | Extension | Handling |
+| --- | --- | --- |
+| PQ restart | `.rst` | Preserves atom names, molecule types, and available velocities or forces |
+| CIF | `.cif` | Read through ASE |
+| XYZ | `.xyz`, `.extxyz` | Reads standard and extended XYZ data |
+| Protein Data Bank | `.pdb` | Read through ASE |
+| MOL / SDF | `.mol`, `.sdf` | Read through ASE |
+| ASE trajectory | `.traj` | Read through ASE |
+
+Multi-frame ASE sources import the final frame. Structures without a cell
+receive a centered vacuum cell. Periodic coordinates follow PQ's
+origin-centered cell convention.
+
+## Workflow
+
+| Step | Result |
 | --- | --- |
-| `PQ --capabilities=json` | Version, compiled features, external calculators, defaults, and supported ranges |
-| `PQ --validate run.in --format=json --scope=installed` | Authoritative parser and setup validation |
+| System | Inspect coordinates, elements, periodic cells, and close contacts |
+| Method | Configure molecular mechanics or one supported QM calculator |
+| Conditions | Build NVE, NVT, or NPT sampling with optional NVT equilibration |
+| Prepare | Wrap periodic atoms and optionally perturb perfect crystal symmetry |
+| Review | Inspect every generated input before creating the package |
 
-This CLI contract is implemented for the planned PQ v0.7 release in
-[PQ pull request #322](https://github.com/MolarVerse/PQ/pull/322). With older
-PQ versions, PQSetup keeps local checks active and states when PQ validation
-was not run.
+PQSetup does not submit jobs or run the simulation.
 
-## What it prepares
+## Validation
 
-- XYZ and PQ restart structures, including collision and periodic-cell checks.
-- Vacuum, NVT, and NPT conditions with the controls supported by PQ v0.6.4.
-- QM and molecular-mechanics inputs with calculator availability diagnostics.
-- Optional NVT equilibration followed by one or more numbered sampling runs.
-- Seeded velocity initialization and optional Gaussian position perturbation.
-- `run-eq.in`, `run-01.in` through `run-999.in`, and a `run.sh` launcher.
+PQSetup checks the structure, plan, required files, and generated inputs
+locally. When the selected PQ executable advertises machine-readable
+validation, PQSetup also checks the inputs with PQ.
 
-Exported launchers write logs to `run-logs/` and stop at the first failed or
-incomplete PQ run.
+Environment detection reports what is available. It does not establish that a
+method, force field, or protocol is scientifically suitable.
 
-## Command line
+PQSetup targets the stable PQ v0.6.4 input schema.
 
-```bash
-pqsetup                              # open the local interface
-pqsetup doctor                       # inspect PQ and calculators
-pqsetup validate run.in              # check an existing input
-pqsetup serve --no-browser           # run without opening a browser
-```
+## Run Packages
 
-Use `--json` with `doctor` or `validate` for machine-readable output.
+| File | Purpose |
+| --- | --- |
+| `run-eq.in` | Optional NVT equilibration |
+| `run-01.in` … `run-999.in` | Sampling inputs and restart chain |
+| Structure restart | Prepared coordinates under the selected start filename |
+| `run.sh` | Fail-fast execution in the recorded order |
+| `pqproject.json` | Plan, environment, provenance, warnings, and file hashes |
 
-## Development
+Uploaded force-field files and calculator templates are included in the
+package.
 
-Node.js 20 or newer is required only when changing the interface.
+## Development
 
 ```bash
 python -m pip install -e ".[dev]"
@@ -101,5 +111,3 @@ python -m pytest
 npm --prefix frontend test
 npm --prefix frontend run build
 ```
-
-PQSetup is available under the [MIT License](LICENSE).

docs/_static/custom.css

@@ -0,0 +1,41 @@
+/* PQSetup-specific additions to Furo. */
+
+.sidebar-logo {
+  width: 4rem;
+}
+
+.sidebar-brand-text {
+  font-weight: 700;
+  letter-spacing: -0.02em;
+}
+
+.sd-card {
+  box-shadow: none;
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+.sd-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.08);
+}
+
+.content p code.literal,
+.content li code.literal {
+  background: var(--color-code-background);
+  border-radius: 0.2em;
+}
+
+.pq-workspace {
+  margin: 1.5rem 0 0;
+}
+
+.pq-workspace img,
+.pq-shot img {
+  width: 100%;
+  border: 1px solid var(--color-foreground-border);
+  border-radius: 0.35rem;
+}
+
+.pq-shot {
+  margin: 1.5rem 0 2rem;
+}

docs/conf.py

@@ -0,0 +1,84 @@
+"""Sphinx configuration for the PQSetup documentation."""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+project = "PQSetup"
+author = "MolarVerse"
+copyright = "2026, the PQSetup authors"
+
+try:
+    from pqsetup import __version__ as release
+except Exception:  # pragma: no cover - package may be absent in a bare checkout
+    release = ""
+version = release
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "sphinx_design",
+]
+
+autodoc_typehints = "description"
+napoleon_numpy_docstring = True
+napoleon_google_docstring = False
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "furo"
+html_title = "PQSetup"
+html_logo = "assets/pq-logo.png"
+html_favicon = "assets/pq-logo.png"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+
+html_theme_options = {
+    "sidebar_hide_name": False,
+    "light_css_variables": {
+        "color-brand-primary": "#1f718f",
+        "color-brand-content": "#176c8c",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#65bddb",
+        "color-brand-content": "#65bddb",
+    },
+    "source_repository": "https://github.com/MolarVerse/PQSetup/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/MolarVerse/PQSetup",
+            "html": (
+                '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
+                'viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 '
+                '3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01'
+                '-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13'
+                '-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 '
+                '2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31'
+                '-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 '
+                '1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 '
+                '1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 '
+                '3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55'
+                '.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>'
+            ),
+            "class": "",
+        },
+    ],
+}
+
+html_baseurl = "https://molarverse.github.io/PQSetup/"