This repository contains the source code for the UCLCHEM documentation website, built with Sphinx and the PyData Sphinx Theme.
The documentation is published at: https://uclchem.github.io
This site is automatically built and deployed using GitHub Actions:
- Trigger: Push to
mainbranch, weekly schedule (Sundays), or manual dispatch - Process:
- Syncs notebooks from uclchem/UCLCHEM repository
- Installs UCLCHEM package from GitHub
- Builds Sphinx documentation with AutoAPI
- Deploys to GitHub Pages
- Build time: ~10-15 minutes (first build), ~5-7 minutes (cached)
See .github/SETUP.md for detailed GitHub Actions configuration.
Quick check:
.github/check-setup.sh- Python 3.10+
- Conda (recommended for environment management)
- A working installation of UCLCHEM (the package being documented)
git clone https://github.com/uclchem/uclchem.github.io.git
cd uclchem.github.io# Create and activate a conda environment (recommended)
conda create -n uclchem-docs python=3.13
conda activate uclchem-docs
# Install Sphinx and theme dependencies
pip install -r requirements.txt
# Install UCLCHEM (the package being documented)
pip install uclchemmake htmlThe built documentation will be in _build/html/.
cd _build/html
python -m http.server 8000Then open http://localhost:8000 in your browser.
.
├── .github/
│ ├── workflows/
│ │ └── deploy-docs.yml # Automated deployment workflow
│ ├── SETUP.md # GitHub Actions setup guide
│ ├── MIGRATION.md # Migration from old deployment method
│ └── check-setup.sh # Setup verification script
├── _static/ # Custom CSS and assets
│ └── custom.css # Leiden Blue branding
├── blog/ # Blog posts (ABlog format)
├── getting-started/ # Installation and quickstart guides
├── tutorials/ # Step-by-step tutorials
├── notebooks/ # Jupyter notebook examples (synced from main repo)
├── user-guide/ # Comprehensive user documentation
├── user_docs/ # Detailed documentation files
├── papers/ # Publication list and citations
├── projects/ # Related projects and ecosystem
├── contributing/ # Contribution guidelines
├── examples/ # Code examples
├── conf.py # Sphinx configuration
├── index.md # Homepage
└── requirements.txt # Python dependencies
# Install dependencies
pip install -r requirements.txt
pip install git+https://github.com/uclchem/UCLCHEM.git
# Sync notebooks (optional - workflow does this automatically)
cp ../uclchem/notebooks/[0-9]*.ipynb notebooks/
# Build
make html
# Preview
cd _build/html && python -m http.server 8000make clean htmlThe deployment workflow (.github/workflows/deploy-docs.yml) performs:
- Notebook Sync: Copies latest numbered notebooks from uclchem/UCLCHEM
- Package Install: Installs UCLCHEM from GitHub main branch
- Documentation Build: Runs Sphinx with AutoAPI and notebook execution
- Deployment: Uploads to GitHub Pages using native Actions
Monitoring:
- View builds: Actions tab
- Check setup: Run
.github/check-setup.sh - Manual trigger: Actions → Build and Deploy Documentation → Run workflow
We welcome contributions! See the Contributing section for guidelines.
- Edit documentation files (
.mdfiles in various directories) - Test locally:
make html - Commit and push to
mainbranch - GitHub Actions will automatically rebuild and deploy
- Setup Guide - Complete GitHub Actions configuration
- Migration Guide - Notes on deployment method updates
- DEPLOYMENT.md - General deployment information
Build fails?
- Check Actions tab for error logs
- Run
.github/check-setup.shto verify configuration - Test locally with
make html
Old content showing?
- Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R)
- Wait 5-10 minutes for CDN propagation
- Check deployment succeeded in Actions tab
Notebooks not updating?
- Workflow syncs notebooks weekly (Sundays)
- Manually trigger: Actions → Run workflow
- Check notebook path in uclchem/UCLCHEM matches workflow
- Cache behavior: By default, notebook execution results are cached in
_build/.jupyter_cache/to speed up local builds. To force fresh execution (matching CI behavior), runrm -rf _build/.jupyter_cachebeforemake html. - UCLCHEM updates: If the UCLCHEM package is updated, reinstall it locally:
pip install --upgrade --force-reinstall git+https://github.com/uclchem/UCLCHEM.git - Notebooks: Tutorial notebooks are copied from the main repository. To test with latest notebooks, copy them manually from the UCLCHEM repo or let CI handle the sync.
Documentation improvements are welcome! To contribute:
- Fork this repository
- Make your changes to markdown files, notebooks, or configuration
- Test locally using the instructions above
- Submit a pull request with a clear description of your changes
For code changes to UCLCHEM itself, please contribute to the main UCLCHEM repository.
- Sphinx - Documentation generator
- PyData Sphinx Theme - Modern, responsive theme
- MyST-NB - Jupyter notebook integration with execution
- Sphinx-AutoAPI - Automatic Python API documentation
- GitHub Actions - Automated build and deployment
- GitHub Pages - Free hosting
uclchem.github.io/
├── .github/workflows/ # GitHub Actions CI/CD
│ └── deploy-docs.yml # Build and deployment workflow
├── _static/ # Static assets (CSS, images, logo)
│ ├── custom.css
│ └── logo.png
├── notebooks/ # Tutorial notebooks (synced from main repo)
│ ├── *.ipynb
│ └── assets/
├── getting-started/ # Getting started guide
├── tutorials/ # Tutorial organization pages
├── user-guide/ # User guide pages
├── api/ # Auto-generated API reference
├── papers.md # Publications
├── projects.md # Related projects
├── blog/ # Blog/news
├── contributing.md # Contribution guide
├── index.md # Homepage
├── conf.py # Sphinx configuration
├── requirements.txt # Python dependencies
├── Makefile # Build commands
└── README.md # This file
- Documentation issues: Open an issue in this repository
- UCLCHEM bugs/features: Open an issue in the main UCLCHEM repository
- Questions: Check the documentation first, then open a discussion
The documentation follows the same license as UCLCHEM. See the main repository for details.
Live site: https://uclchem.github.io/
Main repository: https://github.com/uclchem/UCLCHEM