Building the Documentation

The documentation is built with Sphinx and the pydata-sphinx-theme, styled after the MolSSI SEAMM documentation.

Build locally

pip install -e ".[docs,gnn,ase]"
cd docs
make html            # the site lands in _build/html
make clean           # removes the build and the generated API stubs

The API reference is generated by autosummary from the docstrings, so the package and its gnn / ase extras must import. The CI build runs with -W, so warnings are errors.

Deployment

.github/workflows/docs.yml builds the site on every push to main with a CPU-only torch and deploys it to GitHub Pages; pull requests build without deploying.

Layout

docs/
  conf.py             Sphinx configuration
  index.rst           landing page
  getting_started/    installation, quickstart, first training
  how_tos/            task-oriented recipes
  user_guide/         reference documentation
  developer_guide/    this section
  background/         design and model-fidelity notes
  examples/           the notebook gallery (index.rst; nb/ is mirrored at build)
  api/                autosummary entry point (stubs generated at build)
  _ext/               the example-gallery directive
  _static/, _templates/   MolSSI palette, logos, footer, autosummary templates

Example gallery

The notebooks under examples/ are published one at a time. .gitignore ignores every notebook until it is un-ignored and committed. docs/examples/index.rst lists all of them with the example-toctree directive: an entry whose notebook is in the checkout is built and linked, every other entry shows its title with a coming soon marker. Each entry is Title <nb/path/to/notebook>. To preview the published site from a tree that holds every notebook, set examples_ready in conf.py or pass -D examples_ready=nb/a,nb/b to the build.