Documenting your code from docstrings to automated builds
summary
Shows a concrete workflow: write docstrings and type hints, render API with Sphinx + extensions (autodoc, napoleon, viewcode), author guides and runnable notebooks with JupyterBook, and automate builds to GitHub Pages using GitHub Actions → gh-pages. Demonstrates numbers from the pre-survey (10 tried Sphinx, 4 succeeded), runs notebooks, uses binder for live demos, and adds docs tests (xdoctest), coverage checks (interrogate/pydocstyle); ends with a live site build and troubleshooting notes.
AI-written summary · about
chapters (20)
- 0:00Intro
- 0:38Jacob Deppen
- 2:24Why does documentation matter
- 2:43Values of documentation
- 4:47Who am I
- 5:58Who am I not
- 6:33Why this tutorial
- 8:09The workflow
- 9:26Sphinx
- 11:24Pros to Sphinx
- 17:15Sticky Notes
- 17:52Clone to local machine
- 20:34Setup environment
- 22:38Explore code
- 29:47Documentation level 1
- 42:26Type annotations
- 44:03Pros Cons
- 46:17Practice module
- 52:17Return type
- 57:17Invalid type
related talks
01h 06mDocument your code
02h 28mWriting Documentation with Sphinx and reStructuredText
36mSphinx autodoc: automated API documentation
30mMaking Your Documentation Interactive with PyScript
23mGitHub Actions & Python
18mThanks, I Made It with Quartodoc
02h 25mModern Python Developer's Toolkit
26mBuild your static site with Python