Robert Helewka
f8a2cf0c3d
- Add Gitea Actions workflow to build and deploy docs on push to main - Generate Sphinx reference documentation for all apps and modules - Deploy versioned and latest docs via rsync over SSH
103 lines
3.5 KiB
YAML
103 lines
3.5 KiB
YAML
name: Build & Deploy Docs
|
|
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
paths:
|
|
- 'mnemosyne/**'
|
|
- 'docs/**'
|
|
- 'pyproject.toml'
|
|
- '.gitea/workflows/docs.yml'
|
|
|
|
jobs:
|
|
build-and-deploy:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v4
|
|
|
|
- name: Set up Python
|
|
uses: actions/setup-python@v5
|
|
with:
|
|
python-version: '3.12'
|
|
|
|
- name: Install package + docs deps
|
|
run: |
|
|
pip install --upgrade pip
|
|
pip install -e ".[docs]"
|
|
|
|
- name: Read version from pyproject.toml
|
|
id: version
|
|
run: |
|
|
VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
|
|
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
|
|
|
|
# ─── Failure-debug trio (REQUIRED) ─────────────────────────────────
|
|
- name: Build HTML
|
|
id: build_html
|
|
run: |
|
|
cd docs
|
|
./regenerate_docs.sh
|
|
continue-on-error: true
|
|
|
|
- name: Print Sphinx error log on failure
|
|
if: steps.build_html.outcome == 'failure'
|
|
run: |
|
|
echo "=== Sphinx error log ==="
|
|
cat /tmp/sphinx-err-*.log 2>/dev/null || echo "(no sphinx error log found)"
|
|
|
|
- name: Fail if build failed
|
|
if: steps.build_html.outcome == 'failure'
|
|
run: exit 1
|
|
# ───────────────────────────────────────────────────────────────────
|
|
|
|
- name: Install rsync + openssh
|
|
run: |
|
|
apt-get update
|
|
apt-get install -y --no-install-recommends rsync openssh-client
|
|
|
|
- name: Configure SSH
|
|
run: |
|
|
mkdir -p ~/.ssh
|
|
printf '%s\n' "${{ secrets.DOCS_DEPLOY_KEY }}" > ~/.ssh/id_ed25519
|
|
chmod 600 ~/.ssh/id_ed25519
|
|
ssh-keyscan -p ${{ vars.DOCS_HOST_PORT }} ${{ vars.DOCS_HOST }} >> ~/.ssh/known_hosts
|
|
|
|
- name: Test SSH connectivity
|
|
run: |
|
|
ssh -o BatchMode=yes -o ConnectTimeout=10 \
|
|
-p ${{ vars.DOCS_HOST_PORT }} -i ~/.ssh/id_ed25519 \
|
|
git@${{ vars.DOCS_HOST }} "id && echo 'SSH OK'"
|
|
|
|
- name: Rsync to versioned path
|
|
run: |
|
|
rsync -av --delete \
|
|
-e "ssh -p ${{ vars.DOCS_HOST_PORT }} -i ~/.ssh/id_ed25519" \
|
|
docs/_build/html/ \
|
|
git@${{ vars.DOCS_HOST }}:/var/www/docs/mnemosyne/${{ steps.version.outputs.version }}/
|
|
|
|
- name: Rsync to latest
|
|
run: |
|
|
rsync -av --delete \
|
|
-e "ssh -p ${{ vars.DOCS_HOST_PORT }} -i ~/.ssh/id_ed25519" \
|
|
docs/_build/html/ \
|
|
git@${{ vars.DOCS_HOST }}:/var/www/docs/mnemosyne/latest/
|
|
|
|
- name: Regenerate versions index
|
|
run: |
|
|
ssh -p ${{ vars.DOCS_HOST_PORT }} -i ~/.ssh/id_ed25519 git@${{ vars.DOCS_HOST }} \
|
|
'python3 - <<PY
|
|
import pathlib
|
|
root = pathlib.Path("/var/www/docs/mnemosyne")
|
|
versions = sorted(
|
|
(p.name for p in root.iterdir() if p.is_dir()),
|
|
reverse=True,
|
|
)
|
|
html = ["<!DOCTYPE html><html><head><title>Mnemosyne Docs</title></head><body>",
|
|
"<h1>Mnemosyne Documentation</h1><ul>"]
|
|
for v in versions:
|
|
html.append(f"<li><a href=\"{v}/\">{v}</a></li>")
|
|
html.append("</ul></body></html>")
|
|
(root / "index.html").write_text("\n".join(html))
|
|
PY'
|