Introduction to Sphinx & Read the Docs
summary
Covers how reStructuredText plus Sphinx generate semantic docs from plain text, with directives, cross-references and code‑block testing; shows an autodoc extension that pulls Python docstrings and Pygments highlighting for many languages; demonstrates a hosted service Read the Docs that auto‑builds from repo hooks, serves versions and translations, and reports ~1.5 million builds and ~150 million page views total (about 9 million/month), so the tooling is mature and production‑proven.
AI-written summary · about
chapters (37)
- 0:00Start
- 0:29WHAT WE WILL TALK ABOUT TODAY
- 1:09WHO AM I
- 1:51WHAT YOU SHOULD DO
- 9:41TECH OVERVIEW
- 11:11LIGHTWEIGHT MARKUP LANGUAGE
- 12:19SEMANTIC MEANING
- 13:29CLASSIC LWML EXAMPLE
- 15:22SEMANTIC MARKUP
- 15:43MARKDOWN VS. REST
- 20:26PACE LEVEL MARKUP
- 20:56DIRECTIVES
- 21:14DIRECTIVE EXAMPLE
- 22:49INTERPRETED TEXT ROLES
- 24:04INTERPRETED TEXT ROLE EXAMPLE
- 25:02EXTENSION POINT REVIEW
- 25:22RESTRUCTUREDTEXT REVIEW
- 27:10BASIC SPHINX LAYOUT
- 27:57BUILD YOUR DOCS
- 30:36CROSS-REFERENCING
- 32:06TONS OF CODE-SPECIFIC MARKUP
- 33:47SYNTAX HIGHLIGHTING
- 34:40EXTENSIONS
- 35:26AUTODOC
- 36:05SPHINX REVIEW
- 37:12READ THE DOCS
- 38:50OPEN SOURCE
- 39:42BEAUTIFUL THEME
- 40:14VERSIONS
- 40:54POST COMMIT HOOKS
- 41:46TRANSLATIONS
- 42:02SEARCH
- 42:30MULTIPLE FORMATS
- 42:55LOTS OF SMALL THINGS
- 43:39RECAP
- 44:03RESOURCES
- 44:22QUESTIONS?
related talks
29mIntroduction to Sphinx & Read the Docs
33mWrite the Docs!
02h 28mWriting Documentation with Sphinx and reStructuredText
27mPractical Sphinx
23mTreating Documentation like Code: a Practical Account
27mGoing from Publican to Read the Docs
41mA Practical Introduction to Docs-As-Code
42mEngineering Documentation