Generate complete Python and C++ API documentation with checked CI

.github/workflows/docs.yml

@@ -0,0 +1,105 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main, docs-autogeneration]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      pages: read
+    defaults:
+      run:
+        shell: bash -el {0}
+    env:
+      OMP_NUM_THREADS: "1"
+      OPENBLAS_NUM_THREADS: "1"
+      MPLBACKEND: Agg
+      QT_QPA_PLATFORM: offscreen
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          miniforge-version: latest
+          activate-environment: ""
+
+      - name: Install native dependencies
+        run: |
+          conda create -y -n pele-docs --override-channels -c conda-forge \
+            python=3.12 pip sundials eigen blas-devel pkg-config doxygen=1.17
+          sudo apt-get update
+          sudo apt-get install -y gcc g++ gfortran libglu1-mesa freeglut3-dev
+
+      - name: Install current package and documentation tools
+        run: |
+          conda activate pele-docs
+          python -m pip install '.[docs,gui]' \
+            -Csetup-args=-Dnative=false -Csetup-args=-Dgui=enabled \
+            -Csetup-args=-Dlammps=disabled -Ccompile-args=-j1
+
+      - name: Build Python and C++ documentation
+        run: |
+          conda activate pele-docs
+          make -C doc check SPHINXOPTS='-n -W --keep-going -E -a'
+
+      - name: Test documentation checker and getting-started example
+        run: |
+          conda activate pele-docs
+          python -I -m unittest discover -s doc/tests
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pele-documentation
+          path: doc/_build/html
+          if-no-files-found: error
+          retention-days: 14
+
+      - uses: actions/configure-pages@v5
+        if: >-
+          vars.DOCS_PUBLISH_ENABLED == 'true' && github.repository == 'pele-python/pele' &&
+          github.event_name != 'pull_request' &&
+          (github.ref == 'refs/heads/main' ||
+          (github.ref == 'refs/heads/docs-autogeneration' && vars.DOCS_PUBLISH_BRANCH == 'docs-autogeneration'))
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc/_build/html
+          retention-days: 14
+
+  deploy:
+    name: Publish documentation
+    # A temporary branch switch allows an approved first deployment before merging.
+    if: >-
+      vars.DOCS_PUBLISH_ENABLED == 'true' && github.repository == 'pele-python/pele' &&
+      github.event_name != 'pull_request' &&
+      (github.ref == 'refs/heads/main' ||
+      (github.ref == 'refs/heads/docs-autogeneration' && vars.DOCS_PUBLISH_BRANCH == 'docs-autogeneration'))
+    needs: build
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -109,4 +109,7 @@ bin/act
 **/*.sqlite
 !pele/**/tests/*.sqlite
 
-**/cython_debug/
+**/cython_debug/
+/doc/_build/
+/doc/generated/
+/doc/doxygen/_build/

README.rst

@@ -132,6 +132,11 @@ installed package. If a build fails, remove the build directory before trying ag
 
   $ rm -rf build
 
+Documentation
+=============
+
+docs are at https://pele-python.github.io/pele/.
+
 Tests
 =====
 

RELEASING.md

@@ -41,7 +41,7 @@ To validate locally, first install C/C++/Fortran compilers, SUNDIALS, Eigen, LAP
 headers, and OpenMP, then run:
 
 ```sh
-python -m pip install build twine
+pip install build twine
 python -m build -Csetup-args=-Dnative=false -Csetup-args=-Dlammps=disabled
 python -m twine check --strict dist/pele-0.1.1.tar.gz
 ```
@@ -87,7 +87,7 @@ A dispatch with the input unchecked validates artifacts without publishing.
 Test a binary installation in a fresh supported environment:
 
 ```sh
-python -m pip install --only-binary=:all: --no-deps --index-url https://test.pypi.org/simple/ \
+pip install --only-binary=:all: --no-deps --index-url https://test.pypi.org/simple/ \
   pele==0.1.1
 ```
 

doc/Makefile

@@ -12,11 +12,12 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+.PHONY: help clean clean_sphinx clean_doxygen html sphinx_html doxygen_xml check dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
+	@echo "  check      to build HTML and check generated APIs and local links"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"
@@ -46,14 +47,17 @@ sphinx_html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-doxygen_html:
+doxygen_xml:
 	cd doxygen && doxygen
 
-combine_sphinx_doxygen: sphinx_html doxygen_html
-	rsync -av doxygen/_build/html/ _build/html/doxygen/
+html: sphinx_html
+
+check: html
+	python check_html.py $(BUILDDIR)/html
+
+# Breathe needs fresh Doxygen XML before any Sphinx builder reads the sources.
+sphinx_html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest: doxygen_xml
 
-html: combine_sphinx_doxygen
-
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

doc/README.md

@@ -0,0 +1,108 @@
+# Building and reviewing the documentation
+
+Use a supported Python environment with pele and its native dependencies
+installed (see the repository README). The docs build imports the current
+package, including compiled extensions; it does not mock pele. Install the docs
+and GUI extras and Doxygen 1.15 or newer (CI uses conda-forge's Doxygen 1.17).
+On Ubuntu the OpenGL imports also need GLU and GLUT:
+
+```sh
+conda install -c conda-forge doxygen=1.17
+sudo apt-get install libglu1-mesa freeglut3-dev
+pip install '.[docs,gui]' \
+  -Csetup-args=-Dgui=enabled -Csetup-args=-Dlammps=disabled -Ccompile-args=-j1
+OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MPLBACKEND=Agg QT_QPA_PLATFORM=offscreen \
+  make -C doc check SPHINXOPTS='-n -W --keep-going -E -a'
+python -I -m unittest discover -s doc/tests
+```
+
+
+
+`doc/Makefile` runs Doxygen first using `doc/doxygen/Doxyfile`. It extracts the
+native source comments into `doc/doxygen/_build/xml`. Exhale builds the complete
+C++ class, namespace, function, and file hierarchy from that XML; Breathe renders
+those entries as Sphinx pages under `generated/cpp`. The C++ reference shares the
+Python site's theme, navigation, search, and signature formatting. Every sidebar
+provides a dedicated C++ navigation section for optimizers, potentials, classes,
+namespaces, functions, and source files. Optimizer and potential topics are
+collected from the native inheritance hierarchy and link to each canonical API
+page. There is one generated C++ reference, with no separately published
+Doxygen HTML site or manually selected duplicate class pages.
+
+Generated XML is filtered before import so private class members, underscore
+helpers, and file-local static helpers remain excluded. Public static class
+methods and protected developer interfaces remain available. File and namespace
+descriptions retain their coverage targets, and Doxygen group descriptions are
+included without repeating their member definitions.
+
+For Python, Sphinx autodoc imports the modules and reads their docstrings.
+Autosummary follows the explicit catalogs in the `.rst` pages and package
+docstrings, using `doc/_templates/autosummary` to generate class, method, and
+attribute pages under `doc/generated`. These catalogs provide the overview.
+The **Developer source API** also collects existing public module, class,
+function, and method docstrings from tracked Python and Cython library files,
+including optional backends and public interfaces defined in underscore-prefixed
+modules. Private classes and methods, underscore-prefixed helpers, and definitions
+nested inside functions are excluded. Python special methods that implement public
+protocols, such as constructors, iteration, and calls, are retained.
+It parses source without
+importing those modules, so an unavailable optional dependency does not hide
+its documentation. Tests and playground code are excluded. Numpydoc renders
+the NumPy-style docstrings. Source declarations and links accompany each entry.
+New source docstrings appear automatically without another catalog edit.
+The version comes from `pyproject.toml`. Generated sources, Doxygen output,
+and final HTML are ignored by Git; edit their inputs instead.
+
+`make -C doc check` builds the combined site, verifies representative Python
+pages and the complete generated C++ reference, then checks local HTML links, anchors,
+images, scripts, and stylesheets. Coverage manifests verify that source
+docstrings and documented Doxygen symbols each have one rendered target in the
+Sphinx site. Missing or duplicate C++ definitions fail the check. The native
+reference includes public and protected developer interfaces and file-level
+functions, including `SimplePairwisePotential` and `CellListPotential`. Private
+class members and file-local helpers are excluded. Its inputs are the library's
+own native source roots, excluding
+the vendored JSON headers and unrelated local `source/gmin` directory.
+`-W --keep-going` makes Sphinx warnings fail
+the build; `-n` also checks unresolved API references. Doxygen's existing source-comment warnings are reported separately;
+they are not fatal. External URLs can be checked with `make -C doc linkcheck`,
+but that requires network access and can fail for unavailable remote sites.
+
+For a clean regeneration, use `make -C doc clean` before the build. To review
+the result, serve `doc/_build/html` locally or download the `pele-documentation`
+artifact from the Documentation workflow. Artifacts are retained for 14 days.
+
+From the repository root, start a local server:
+
+```sh
+python -m http.server 8765 --directory doc/_build/html
+```
+
+Open http://localhost:8765/ in your browser.
+
+## CI and publication
+
+`.github/workflows/docs.yml` builds and checks documentation for pushes to
+`docs-autogeneration` and `main`, PRs targeting `main`, and manual runs. Every
+successful build uploads both the review site and a deployable Pages artifact.
+PRs cannot deploy. CI builds the current checkout with native dependencies and
+serial compilation.
+
+Publication is disabled unless the repository variable `DOCS_PUBLISH_ENABLED`
+is exactly `true`. Pages must use **GitHub Actions** as its publishing source.
+Successful `main` builds then refresh the website; manual main runs use the
+same deployment path. No custom deployment secret is needed: the deploy job
+uses GitHub's Pages and OIDC permissions.
+
+For an owner-approved first deployment before merging, temporarily set the
+repository variable `DOCS_PUBLISH_BRANCH=docs-autogeneration` as well, then push
+to that branch. Remove that variable after the deployment succeeds so later
+docs-branch edits only build and check. Keep the old `gh-pages` branch for
+rollback. Artifacts expire after 14 days; rerun the build if necessary.
+
+Publishing is a separate owner-approved action from preparing a PR. Repository
+and environment review requirements can be configured separately; the
+`github-pages` environment name in YAML alone does not require approval.
+Installation and getting-started pages are the first website review priority;
+the older custom-potential and system-class tutorials still need a separate
+Python 3 content review.

doc/_static/pele.css

@@ -0,0 +1,32 @@
+/* Give api_navigation.html the look of Shibuya's toctree captions and links. */
+.globaltoc > h3 {
+  font-size: .86rem;
+  font-weight: 500;
+  font-family: var(--sy-f-heading);
+  color: var(--sy-c-light);
+  border-top: 1px solid var(--sy-c-divider);
+  padding: .8rem 0 .4rem;
+}
+.globaltoc > h3:first-of-type {
+  border-top: none;
+  padding-top: 0;
+}
+.globaltoc > ul {
+  margin-bottom: 1.5rem;
+}
+.globaltoc a[aria-current="page"] {
+  color: var(--sy-c-link);
+  font-weight: 500;
+}
+
+/* Shibuya moves direct signature links onto their own line as viewcode "[source]"
+   links. In C/C++ signatures those links are base classes, so keep them inline. */
+.sig.cpp > a.internal,
+.sig.c > a.internal {
+  color: var(--yue-c-link-1);
+  font-size: inherit;
+}
+.sig.cpp > a.internal::before,
+.sig.c > a.internal::before {
+  content: none;
+}