Automate Documentation with Sphinx & GitHub Actions
summary
Shows how to generate HTML docs from real docstrings using Sphinx autodoc + Napoleon, builds per-module rst with sphinx-apidoc, applies the furo theme, and hosts the output on an orphan gh-pages branch so the site is served via actions/github-pages. Demonstrates a GitHub Actions workflow that installs dependencies, runs sphinx-build (or sphinx-multiversion for versions), and publishes on a release trigger; the example repo produces a live site with multiple versioned directories and an index redirect that already works.
AI-written summary · about
chapters (16)
- 0:00Workshop introduction
- 1:05What is Sphinx
- 2:06How this workshop came to be
- 3:10Workshop setup
- 4:17Environment setup
- 8:15Sphinx basics
- 10:26reStructuredText
- 12:13API docstrings
- 16:50Generating HTML documentation
- 19:21Theme customization
- 22:35GitHub Pages hosting
- 27:24Break
- 28:08Automation with GitHub Actions
- 36:02Documentation versioning
- 42:06Versioned docs automation
- 45:17Workshop conclusion and feedback
related talks
27mPractical Sphinx
02h 28mWriting Documentation with Sphinx and reStructuredText
50m360° automation with GitHub Actions
33mWrite the Docs!
18mAutomating All the Code & Testing Things with GitHub Actions
18mDeveloper Workflow Automation with GitHub Actions (CI/CD)
36mBuilding Docs like Code: Continuous Integration for Documentation
23mTreating Documentation like Code: a Practical Account