Practical Sphinx
summary
Practical steps for Sphinx: combine reStructuredText Markdown and Jupyter Notebooks using nbsphinx and pandoc, keep conf.py as executable config, run make clean then make html and make linkcheck to catch broken links, wire builds into Travis CI and ReadTheDocs for automated testing and publishes, use autodoc and Napoleon to pull docstrings into docs, monitor dozens of repos with a simple badge dashboard (44 repos in one example) and iterate content rather than rewrite everything.
AI-written summary · about
chapters (8)
- 0:00Intro
- 1:15Challenges
- 8:21Content
- 12:21Drafting
- 13:48Visuals
- 15:44Structure
- 18:03Monitoring
- 19:40Extensions
related talks
33mWrite the Docs!
02h 28mWriting Documentation with Sphinx and reStructuredText
45mIntroduction to Sphinx & Read the Docs
29mIntroduction to Sphinx & Read the Docs
46mAutomate Documentation with Sphinx & GitHub Actions
41mA Practical Introduction to Docs-As-Code
19mWhere Docs, Cloud-hosted Interactive Tutorials and CI Testing Intersect
23mTreating Documentation like Code: a Practical Account