Skip to content

Commit 4eb07e4

Browse files
GijsVermarienGijsVermarien
committed
created sphinx based documentation
0 parents  commit 4eb07e4

83 files changed

Lines changed: 7263 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ARCHITECTURE.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# GitHub Actions Workflow Architecture
2+
3+
## Overview
4+
5+
This document describes the GitHub Actions workflow used to build and deploy the site at https://uclchem.github.io.
6+
7+
### Triggers
8+
9+
- Push to `main` (automatic deploy)
10+
- Weekly scheduled run (Sunday 00:00 UTC)
11+
- Manual `workflow_dispatch` from Actions tab
12+
13+
### Build job (summary)
14+
15+
1. Checkout this repository (`uclchem/uclchem.github.io`, branch: `main`)
16+
2. Set up Python environment (Ubuntu, Python 3.12) and enable pip caching
17+
3. Install system dependencies (e.g., `gfortran`)
18+
4. Sync notebooks and assets from the main UCLCHEM repository:
19+
- Clone `https://github.com/uclchem/UCLCHEM.git`
20+
- Copy numbered notebooks into `./notebooks/` and any notebook assets
21+
- Copy `answer/uclchem.png` → `./_static/logo.png` (if present)
22+
5. Install UCLCHEM (pip install from GitHub) and documentation dependencies (`pip install -r requirements.txt`)
23+
6. Clear caches (`rm -rf _build/.jupyter_cache`)
24+
7. Build Sphinx docs (`make html`): execute notebooks (optional), generate API via AutoAPI, render blog
25+
8. Upload build artifact (`./_build/html`) for deployment
26+
27+
### Deploy job (summary)
28+
29+
- Runs after a successful build on `main`
30+
- Uses `actions/deploy-pages@v4` with the uploaded artifact
31+
- Deploys to GitHub Pages environment `github-pages` at `https://uclchem.github.io`
32+
33+
## Data flow (concise)
34+
35+
- Source repo: `uclchem/UCLCHEM` (notebooks, package source, assets)
36+
- Doc repo: `uclchem/uclchem.github.io` (Sphinx sources, config)
37+
- On build: notebooks and assets are pulled from the source repo → Sphinx builds → `_build/html` → GitHub Pages
38+
39+
---
40+
41+
(See the sections below for features, triggers, permissions, timings and verification steps.)
42+
43+
44+
## Data Flow
45+
46+
```
47+
uclchem/UCLCHEM uclchem/uclchem.github.io
48+
(main repository) (documentation repository)
49+
│ │
50+
│ │
51+
├─ notebooks/*.ipynb ────────────────▶│ notebooks/*.ipynb
52+
│ │
53+
├─ src/uclchem/ ──┐ │
54+
│ │ │
55+
│ [pip install] ────────────▶│ (UCLCHEM package)
56+
│ │
57+
└─ answer/uclchem.png ───────────────▶│ _static/logo.png
58+
│
59+
├─ conf.py
60+
├─ *.md files
61+
├─ blog/*.md
62+
├─ user_docs/*.md
63+
│
64+
[Sphinx Build]
65+
│
66+
▼
67+
_build/html/
68+
│
69+
[GitHub Pages]
70+
│
71+
▼
72+
https://uclchem.github.io
73+
```
74+
75+
## Key Features
76+
77+
### Automatic Synchronization
78+
- **Source:** uclchem/UCLCHEM repository notebooks
79+
- **Destination:** uclchem.github.io/notebooks
80+
- **Frequency:** On every build (push, weekly, or manual)
81+
- **Pattern:** `[0-9]*.ipynb` (numbered notebooks only)
82+
83+
### Build Process
84+
- **Sphinx:** Converts .md/.rst → HTML
85+
- **myst-nb:** Executes and renders Jupyter notebooks
86+
- **AutoAPI:** Generates Python API documentation from UCLCHEM source
87+
- **ABlog:** Renders blog posts with timestamps and categories
88+
89+
### Deployment Method
90+
- **Type:** GitHub Actions native (modern)
91+
- **Old method:** ~~peaceiris/actions-gh-pages~~ (deprecated)
92+
- **New method:** actions/upload-pages-artifact + actions/deploy-pages
93+
- **Branch:** No gh-pages branch needed
94+
- **Environment:** github-pages (tracked in repo)
95+
96+
## Triggers
97+
98+
| Event | When | Description |
99+
|-------|------|-------------|
100+
| `push` | On commit to `main` | Immediate deployment of changes |
101+
| `schedule` | Sunday 00:00 UTC | Weekly sync of notebooks from main repo |
102+
| `workflow_dispatch` | Manual | Trigger from Actions tab |
103+
104+
## Permissions Required
105+
106+
```yaml
107+
permissions:
108+
contents: read # Read repository content
109+
pages: write # Deploy to GitHub Pages
110+
id-token: write # OIDC token for Pages deployment
111+
```
112+
113+
## Concurrency Control
114+
115+
```yaml
116+
concurrency:
117+
group: "pages"
118+
cancel-in-progress: true
119+
```
120+
121+
- Only one deployment at a time
122+
- New deployments cancel pending ones
123+
- Prevents conflicts from simultaneous builds
124+
125+
## Build Time
126+
127+
| Phase | Duration | Notes |
128+
|-------|----------|-------|
129+
| Setup (Python, gfortran) | ~1-2 min | Cached |
130+
| Notebook sync | ~30 sec | Shallow clone |
131+
| UCLCHEM install | ~2-3 min | From GitHub |
132+
| Sphinx build | ~5-10 min | Notebook execution |
133+
| Upload & deploy | ~1-2 min | Artifact transfer |
134+
| **Total** | **~10-15 min** | First run |
135+
| **Total (cached)** | **~5-7 min** | Subsequent runs |
136+
137+
## Verification Steps
138+
139+
After deployment:
140+
141+
1. ✅ Check Actions tab for green checkmark
142+
2. ✅ Verify deployment environment shows correct URL
143+
3. ✅ Visit https://uclchem.github.io
144+
4. ✅ Check notebooks are present and rendered
145+
5. ✅ Verify API documentation exists at /api/
146+
6. ✅ Check blog posts at /blog/
147+
148+
## Monitoring
149+
150+
### Success Indicators
151+
- Build job completes without errors
152+
- Deploy job shows deployment URL
153+
- Site is accessible at https://uclchem.github.io
154+
- Notebooks, API docs, and blog are all present
155+
156+
### Failure Indicators
157+
- Red X in Actions tab
158+
- Error messages in job logs
159+
- 404 errors on site
160+
- Missing content sections
161+
162+
### Debugging
163+
1. Click failed workflow run
164+
2. Expand failed step
165+
3. Review error messages
166+
4. Check logs for specific issues
167+
5. Test locally: `make html`
168+
169+
## Repository Settings
170+
171+
Required GitHub Pages configuration:
172+
173+
```
174+
Settings → Pages
175+
Source: GitHub Actions ← CRITICAL!
176+
177+
Settings → Actions → General
178+
Workflow permissions: Read and write
179+
```
180+
181+
## File Locations
182+
183+
| File | Purpose |
184+
|------|---------|
185+
| `.github/workflows/deploy-docs.yml` | Main workflow definition |
186+
| `.github/SETUP.md` | Complete setup instructions |
187+
| `.github/MIGRATION.md` | Migration notes from old method |
188+
| `.github/check-setup.sh` | Setup verification script |
189+
| `requirements.txt` | Python dependencies |
190+
| `conf.py` | Sphinx configuration |
191+
| `Makefile` | Build shortcuts |

‎.github/MIGRATION.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# GitHub Actions Migration Summary
2+
3+
## What Changed
4+
5+
The workflow has been updated to use GitHub's modern Pages deployment action instead of the legacy `peaceiris/actions-gh-pages` approach.
6+
7+
### Old Approach (peaceiris/actions-gh-pages)
8+
9+
```yaml
10+
jobs:
11+
build-and-deploy:
12+
runs-on: ubuntu-latest
13+
steps:
14+
# ... build steps ...
15+
- name: Deploy to GitHub Pages
16+
uses: peaceiris/actions-gh-pages@v4
17+
with:
18+
github_token: ${{ secrets.GITHUB_TOKEN }}
19+
publish_dir: ./_build/html
20+
force_orphan: true
21+
```
22+
23+
**Issues:**
24+
- Uses `gh-pages` branch for deployment
25+
- Requires managing orphan branches
26+
- Less integration with GitHub Pages settings
27+
- Limited deployment tracking
28+
29+
### New Approach (GitHub Native)
30+
31+
```yaml
32+
jobs:
33+
build:
34+
runs-on: ubuntu-latest
35+
steps:
36+
# ... build steps ...
37+
- name: Upload Pages artifact
38+
uses: actions/upload-pages-artifact@v3
39+
with:
40+
path: ./_build/html
41+
42+
deploy:
43+
needs: build
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
steps:
48+
- name: Deploy to GitHub Pages
49+
uses: actions/deploy-pages@v4
50+
```
51+
52+
**Benefits:**
53+
- ✅ Native GitHub Pages integration
54+
- ✅ No `gh-pages` branch needed
55+
- ✅ Better deployment tracking via environments
56+
- ✅ Automatic URL output
57+
- ✅ Cleaner repository history
58+
- ✅ Built-in concurrency control
59+
60+
## Required GitHub Settings
61+
62+
### In Repository Settings → Pages
63+
64+
**Old setup:**
65+
- Source: Deploy from branch
66+
- Branch: gh-pages / root
67+
68+
**New setup:**
69+
- Source: **GitHub Actions** ← Important!
70+
71+
### Permissions
72+
73+
Both approaches need:
74+
- Settings → Actions → General → Workflow permissions: Read and write
75+
76+
New approach also needs (auto-configured by workflow):
77+
```yaml
78+
permissions:
79+
contents: read
80+
pages: write
81+
id-token: write
82+
```
83+
84+
## Key Features Retained
85+
86+
✅ Notebook synchronization from UCLCHEM repository
87+
✅ UCLCHEM package installation from GitHub
88+
✅ Sphinx build with AutoAPI
89+
✅ Weekly automatic rebuilds
90+
✅ Manual workflow dispatch
91+
✅ Pip caching for faster builds
92+
93+
## Migration Checklist
94+
95+
- [x] Updated workflow file with new deployment actions
96+
- [x] Added proper permissions and concurrency controls
97+
- [x] Split build and deploy into separate jobs
98+
- [x] Added GitHub Pages environment configuration
99+
- [x] Maintained all existing build steps
100+
- [x] Preserved notebook sync logic
101+
- [ ] **User action:** Change GitHub Pages source to "GitHub Actions" in repository settings
102+
- [ ] **User action:** Trigger first workflow run to test deployment
103+
- [ ] **User action:** Delete old `gh-pages` branch after successful deployment (optional)
104+
105+
## Testing the New Workflow
106+
107+
1. **Ensure Pages source is set to "GitHub Actions":**
108+
- Go to repository Settings → Pages
109+
- Under "Build and deployment" → Source
110+
- Select "GitHub Actions"
111+
112+
2. **Trigger a test build:**
113+
- Go to Actions tab
114+
- Select "Build and Deploy Documentation"
115+
- Click "Run workflow"
116+
- Wait for completion (~10-15 minutes)
117+
118+
3. **Verify deployment:**
119+
- Check the "deploy" job shows the deployment URL
120+
- Visit https://uclchem.github.io
121+
- Verify notebooks, API docs, and blog are present
122+
123+
4. **Clean up (optional):**
124+
```bash
125+
# After successful deployment, delete old gh-pages branch
126+
git push origin --delete gh-pages
127+
```
128+
129+
## Rollback Plan
130+
131+
If issues occur, you can temporarily revert:
132+
133+
1. Checkout previous commit:
134+
```bash
135+
git revert HEAD
136+
git push origin main
137+
```
138+
139+
2. Or manually restore in GitHub:
140+
- Go to Settings → Pages
141+
- Change source back to "Deploy from branch"
142+
- Select branch: `gh-pages`
143+
144+
## Further Reading
145+
146+
- [GitHub Pages deployment with Actions](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)
147+
- [upload-pages-artifact action](https://github.com/actions/upload-pages-artifact)
148+
- [deploy-pages action](https://github.com/actions/deploy-pages)

0 commit comments

Comments
 (0)