stanmoore1 · stanmoore1 · Aug 24, 2026 · Aug 24, 2026 · Aug 26, 2026 · Aug 26, 2026
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -165,3 +165,33 @@ jobs:
 
     - name: Build
       run: cd build; make -j4
+
+  # The manual is Sphinx now, and nothing else in this workflow would notice
+  # if it stopped building.  -W turns Sphinx's warnings into errors, so a
+  # broken cross-reference or a malformed table fails the pull request
+  # rather than reaching the web site; --keep-going reports all of them
+  # instead of stopping at the first.
+  doc:
+    runs-on: ubuntu-22.04
+    # Both ends of the Python range, because they do not resolve to the
+    # same Sphinx and the two do not report the same things.  Sphinx 9
+    # requires Python 3.11, so pip gives 3.9 the newest 7.x instead --
+    # and 7.x reported 13 duplicate-target warnings that 9.x does not.
+    # Testing only the newer one meant a clean CI while a contributor on
+    # an older python saw a wall of warnings.
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.11']
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Build the manual
+      run: make -C doc html SPHINXEXTRA="-W --keep-going"
+
+    - name: Check every internal link and anchor resolves
+      run: python3 doc/utils/link-check.py doc/html
diff --git a/README b/README
@@ -34,9 +34,20 @@ python                     Python wrapper on SPARTA as a library
 src                        source files
 tools                      pre- and post-processing tools
 
-Point your browser at any of these files to get started:
-
-doc/Manual.html	           the SPARTA manual
-doc/Section_intro.html	   hi-level introduction to SPARTA
-doc/Section_start.html	   how to build and use SPARTA
-doc/Developer.pdf          SPARTA developer guide
+The manual is built from reStructuredText sources in doc/src with
+Sphinx, which is installed into a virtualenv on the first build, so the
+only prerequisite is a python3 with venv.  The targets are:
+
+make -C doc html          the manual, in doc/html
+make -C doc pdf           doc/html/Manual.pdf (needs latexmk and pdflatex)
+make -C doc fasthtml      quick per-page preview, in doc/fasthtml (needs
+                          pandoc); "make -C doc fasthtml/read_surf.html"
+                          rebuilds just that page, for checking an edit
+make -C doc check         verify every internal link and anchor resolves
+
+"make -C doc" on its own lists these with the rest.  Then point your
+browser at any of these files to get started:
+
+doc/html/Manual.html	   the SPARTA manual
+doc/html/Section_intro.html   hi-level introduction to SPARTA
+doc/html/Section_start.html   how to build and use SPARTA
diff --git a/data/README b/data/README
@@ -31,10 +31,10 @@ and are read by the surf_react command.
 These are the doc pages for various commands which describe the format
 of the corresponding files:
 
-species = doc/species.html
-species.vib = doc/species.html
-vss/vhs/hs = doc/collide.html
-tce = doc/react.html
-sdata = doc/read_surf.html
-stl = doc/Section_tools.html#stl2surf
-surf = doc/surf_react.html
+species = doc/html/species.html
+species.vib = doc/html/species.html
+vss/vhs/hs = doc/html/collide.html
+tce = doc/html/react.html
+sdata = doc/html/read_surf.html
+stl = doc/html/Section_tools.html#stl2surf
+surf = doc/html/surf_react.html
diff --git a/doc/.gitignore b/doc/.gitignore
@@ -0,0 +1,9 @@
+/html
+/doctrees
+/latex
+/latexdoctrees
+/fasthtml
+/docenv
+*.pyc
+__pycache__
+/utils/sphinx-config/_static/mathjax
diff --git a/doc/Eqs/GS_list.png b/doc/Eqs/GS_list.png
diff --git a/doc/Eqs/GS_list.tex b/doc/Eqs/GS_list.tex
diff --git a/doc/Eqs/PS_list.png b/doc/Eqs/PS_list.png
diff --git a/doc/Eqs/PS_list.tex b/doc/Eqs/PS_list.tex
diff --git a/doc/Eqs/arrhenius.jpg b/doc/Eqs/arrhenius.jpg
diff --git a/doc/Eqs/arrhenius.tex b/doc/Eqs/arrhenius.tex
diff --git a/doc/Eqs/arrhenius_2.png b/doc/Eqs/arrhenius_2.png
diff --git a/doc/Eqs/arrhenius_2.tex b/doc/Eqs/arrhenius_2.tex
diff --git a/doc/Eqs/cell_timestep.jpg b/doc/Eqs/cell_timestep.jpg
diff --git a/doc/Eqs/cell_timestep.tex b/doc/Eqs/cell_timestep.tex
diff --git a/doc/Eqs/diffuse_normal.jpg b/doc/Eqs/diffuse_normal.jpg
diff --git a/doc/Eqs/diffuse_normal.tex b/doc/Eqs/diffuse_normal.tex
diff --git a/doc/Eqs/impulsive_phi.JPG b/doc/Eqs/impulsive_phi.JPG
diff --git a/doc/Eqs/impulsive_phi.tex b/doc/Eqs/impulsive_phi.tex
diff --git a/doc/Eqs/impulsive_softsphere.JPG b/doc/Eqs/impulsive_softsphere.JPG
diff --git a/doc/Eqs/impulsive_softsphere.tex b/doc/Eqs/impulsive_softsphere.tex
diff --git a/doc/Eqs/impulsive_step.JPG b/doc/Eqs/impulsive_step.JPG
diff --git a/doc/Eqs/impulsive_step.tex b/doc/Eqs/impulsive_step.tex
diff --git a/doc/Eqs/impulsive_tempvar.JPG b/doc/Eqs/impulsive_tempvar.JPG
diff --git a/doc/Eqs/impulsive_tempvar.tex b/doc/Eqs/impulsive_tempvar.tex
diff --git a/doc/Eqs/impulsive_theta.JPG b/doc/Eqs/impulsive_theta.JPG
diff --git a/doc/Eqs/impulsive_theta.tex b/doc/Eqs/impulsive_theta.tex
diff --git a/doc/Eqs/impulsive_u0.JPG b/doc/Eqs/impulsive_u0.JPG
diff --git a/doc/Eqs/impulsive_u0.tex b/doc/Eqs/impulsive_u0.tex
diff --git a/doc/Eqs/k_energy.png b/doc/Eqs/k_energy.png
diff --git a/doc/Eqs/k_energy.tex b/doc/Eqs/k_energy.tex
diff --git a/doc/Eqs/k_kisliuk.png b/doc/Eqs/k_kisliuk.png
diff --git a/doc/Eqs/k_kisliuk.tex b/doc/Eqs/k_kisliuk.tex
diff --git a/doc/Eqs/lambda.png b/doc/Eqs/lambda.png
diff --git a/doc/Eqs/lambda.tex b/doc/Eqs/lambda.tex
diff --git a/doc/Eqs/lambda_old.jpg b/doc/Eqs/lambda_old.jpg
diff --git a/doc/Eqs/qk_dissociation.jpg b/doc/Eqs/qk_dissociation.jpg
diff --git a/doc/Eqs/qk_dissociation.tex b/doc/Eqs/qk_dissociation.tex
diff --git a/doc/Eqs/qk_exchange.jpg b/doc/Eqs/qk_exchange.jpg
diff --git a/doc/Eqs/qk_exchange.tex b/doc/Eqs/qk_exchange.tex
diff --git a/doc/Eqs/tau.jpg b/doc/Eqs/tau.jpg
diff --git a/doc/Eqs/tau.png b/doc/Eqs/tau.png
diff --git a/doc/Eqs/tau.tex b/doc/Eqs/tau.tex
diff --git a/doc/Eqs/td_barrier_Tnorm.JPG b/doc/Eqs/td_barrier_Tnorm.JPG
diff --git a/doc/Eqs/td_barrier_Tnorm.tex b/doc/Eqs/td_barrier_Tnorm.tex
diff --git a/doc/Eqs/td_barrier_dist.JPG b/doc/Eqs/td_barrier_dist.JPG
diff --git a/doc/Eqs/td_barrier_dist.tex b/doc/Eqs/td_barrier_dist.tex
diff --git a/doc/Eqs/td_bond.JPG b/doc/Eqs/td_bond.JPG
diff --git a/doc/Eqs/td_bond.tex b/doc/Eqs/td_bond.tex
diff --git a/doc/Eqs/td_initenergy.JPG b/doc/Eqs/td_initenergy.JPG
diff --git a/doc/Eqs/td_initenergy.tex b/doc/Eqs/td_initenergy.tex
diff --git a/doc/Eqs/time_counter.png b/doc/Eqs/time_counter.png
diff --git a/doc/Eqs/time_counter.tex b/doc/Eqs/time_counter.tex