improved-octo-fortnight

A reference implementation of documentation workflows.

📚 Demo site

Features

Content

• Built with zensical
• API reference auto-generated using mkdocstrings

This repo documents a Python package. The setup should work for other languages with minor modifications.

Deployment

• Deployed to GitHub Pages via GitHub Actions
• Separate docs for each release and development branch
• Docs preview for each PR

GitHub Pages structure

The deployed site is structured as follows:

/
├── index.html          # auto-generated version index
├── latest/             # copy of the latest release
├── dev/                # built from main
├── 2.0.0/              # release versions
├── 1.1.0/
├── 1.0.0/
└── pr/
    ├── 14/             # PR preview
    └── 13/

GitHub Actions workflows

These workflows build, deploy, and clean up the documentation:

Workflow	Trigger	Deploys to
docs-dev.yml	Push to main	/dev/, index.html
docs-release.yml	Release	/<version>/, /latest/, index.html
docs-pr-preview.yml	PR opened/updated	/pr/<number>/
docs-pr-cleanup.yml	PR closed	removes /pr/<number>/

The workflows require the GitHub settings

• Settings > Pages > Source > Deploy from a branch > gh-pages (root /)