SUMMARY and RESULTS markdowns

Author: SidRichardsQuantum

.github/workflows/docs.yml

@@ -30,6 +30,11 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install -e ".[docs]"
 
+      - name: Check benchmark artifacts
+        run: |
+          python scripts/export_benchmark_artifacts.py
+          git diff --exit-code notebooks/benchmarks/RESULTS.md notebooks/benchmarks/_artifacts
+
       - name: Build docs
         run: |
           python -m sphinx -W -b html docs docs/_build/html

.github/workflows/package.yml

@@ -73,6 +73,7 @@ jobs:
               "__pycache__",
               ".pyc",
               ".pytest_cache",
+              "/notebooks/benchmarks/_artifacts/",
               "/results/",
               "/images/",
               "/vendor_wheels/",
@@ -97,6 +98,9 @@ jobs:
           if not any(name.endswith("tests/test_notebook_validation.py") for name in sdist_names):
               raise SystemExit("Expected tests to be included in sdist")
 
+          if any(name.endswith("tests/test_benchmark_artifacts.py") for name in sdist_names):
+              raise SystemExit("Repository-only benchmark artifact tests must not be included in sdist")
+
           print(f"wheel: {wheel.name} ({len(wheel_names)} files)")
           print(f"sdist: {sdist.name} ({len(sdist_names)} files)")
           PY

.github/workflows/pages.yml

@@ -38,14 +38,17 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install -e ".[docs]"
 
+      - name: Check benchmark artifacts
+        run: |
+          python scripts/export_benchmark_artifacts.py
+          git diff --exit-code notebooks/benchmarks/RESULTS.md notebooks/benchmarks/_artifacts
+
       - name: Build docs
         run: |
           python -m sphinx -W -b html docs docs/_build/html
 
       - name: Configure Pages
         uses: actions/configure-pages@v5
-        with:
-          enablement: true
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3

CHANGELOG.md

@@ -4,6 +4,81 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.3.24] - April 20, 2026
+
+### Added
+
+- **Published Sphinx documentation site**
+
+  Added a Sphinx/Furo documentation shell around the existing `README.md`,
+  `USAGE.md`, `THEORY.md`, `notebooks/README_notebooks.md`, and `more_docs/`
+  content.
+
+  The docs build supports MyST Markdown, Mermaid diagrams, API autodoc pages,
+  strict Sphinx builds, and GitHub Pages deployment.
+
+- **Benchmark summary and results pages**
+
+  Added benchmark documentation pages for:
+
+  - `notebooks/benchmarks/SUMMARY.md`
+  - `notebooks/benchmarks/RESULTS.md`
+  - `notebooks/benchmarks/MAINTENANCE.md`
+
+  These pages summarize the benchmark notebook inventory, method-selection
+  guidance, artifact policy, and result-bearing notebooks.
+
+- **Curated benchmark artifact export flow**
+
+  Added `scripts/export_benchmark_artifacts.py` to promote selected local
+  benchmark outputs into tracked, curated artifacts under
+  `notebooks/benchmarks/_artifacts/`.
+
+  The exporter currently publishes selected figures and CSV/Markdown tables for:
+
+  - H2 ansatz comparison
+  - H2 mapping comparison
+  - low-qubit VQE benchmark
+  - H2 cross-method runtime
+  - LiH cross-method results
+  - QPE H2 decision-map summaries
+  - H2 noise-robustness reference results
+
+- **Benchmark artifact regression tests**
+
+  Added tests that verify `RESULTS.md` references existing curated artifacts,
+  enforce a small set of expected artifact file types, guard against oversized
+  artifact files, and confirm the benchmark exporter is idempotent.
+
+### Changed
+
+- **Documentation URLs and Pages workflows**
+
+  Updated the package documentation URL and README badge/link to point at the
+  GitHub Pages documentation site.
+
+  Added docs and Pages workflow checks that run the benchmark artifact exporter
+  and fail if curated artifacts are stale.
+
+- **Benchmark artifact policy**
+
+  Kept raw `results/` and `images/` ignored while tracking only curated,
+  reviewed copies under `notebooks/benchmarks/_artifacts/`.
+
+### Fixed
+
+- **Generated artifact cleanup**
+
+  Removed stale local smoke/cache result files and orphaned generated images from
+  the ignored artifact directories, leaving only referenced generated images in
+  the local `images/` directory.
+
+## [0.3.23] - April 20, 2026
+
+### Changed
+
+- Published the initial GitHub Pages documentation release.
+
 ## [0.3.22] - April 20, 2026
 
 ### Added

MANIFEST.in

@@ -19,11 +19,17 @@ recursive-include notebooks *.md
 # same smoke/regression suite against the sdist. These are not included in the
 # wheel because package discovery is restricted to the runtime package modules.
 recursive-include tests *.py *.ipynb
+exclude tests/test_benchmark_artifacts.py
 
 # Exclude notebooks themselves (huge)
 exclude notebooks/*.ipynb
 exclude notebooks/**/*.ipynb
 
+# Exclude curated benchmark artifacts from the sdist. They are tracked in the
+# repository for the docs site, but they are generated result artifacts rather
+# than source-package inputs.
+prune notebooks/benchmarks/_artifacts
+
 # Exclude large data directories
 prune data
 prune results

docs/benchmarks/_artifacts

@@ -0,0 +1 @@
+../../notebooks/benchmarks/_artifacts

docs/benchmarks/results.md

@@ -0,0 +1,2 @@
+```{include} ../../notebooks/benchmarks/RESULTS.md
+```

docs/benchmarks/summary.md

@@ -0,0 +1,2 @@
+```{include} ../../notebooks/benchmarks/SUMMARY.md
+```

docs/conf.py

@@ -23,7 +23,7 @@
 }
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "benchmarks/_artifacts", "Thumbs.db", ".DS_Store"]
 
 html_theme = "furo"
 html_title = project

docs/index.md

@@ -19,6 +19,15 @@ Notebooks <user/notebooks>
 architecture
 ```
 
+```{toctree}
+:maxdepth: 1
+:titlesonly:
+:caption: Benchmarks
+
+Benchmark Summary <benchmarks/summary>
+Benchmark Results <benchmarks/results>
+```
+
 ```{toctree}
 :maxdepth: 1
 :titlesonly: