Write the Docs!
summary
Claims that Sphinx + reStructuredText turns plain files into versioned HTML/PDF docs with five init commands and about eight build commands, and that nbSphinx embeds executed Jupyter notebooks (figures and all). Describes deploying to Read the Docs or a private server via Azure App Service and CI/CD, notes a small team (2–3 people) and sensitive datasets (mortality on ~25 million lives). Shows autogenerated API reference from docstrings and live onboarding site; the workflow actually builds and serves the docs.
AI-written summary · about
chapters (12)
- 0:00Write the Docs intro
- 1:59Why docs matter for small teams
- 5:10Sphinx and why use it
- 8:49reStructuredText vs Markdown
- 10:35reStructuredText directives
- 16:20Build and view Sphinx docs
- 20:57Docs from docstrings
- 22:41Custom Sphinx themes
- 24:51Deploy docs with Read the Docs
- 27:18Jupyter notebooks in docs
- 29:48How Sphinx processes docs
- 31:12Docs types best practices
related talks
45mIntroduction to Sphinx & Read the Docs
29mIntroduction to Sphinx & Read the Docs
27mPractical Sphinx
02h 28mWriting Documentation with Sphinx and reStructuredText
19mWhere Docs, Cloud-hosted Interactive Tutorials and CI Testing Intersect
23mTreating Documentation like Code: a Practical Account
42mEngineering Documentation
22mAutomating API Documentation