Switching from Sphinx to Markdown
summary
Migrating from Sphinx/reStructuredText to Markdown proves practical: automated conversion with pandock plus custom regex scripts, plugins like MkDocs themes and mkdocstrings, and a shared tooling repo produce a unified site and live-preview builds that are far faster. The migration of a multi-project ecosystem takes about nine months end to end, with individual parts ranging from three days to three months; the result is unified, type-aware API docs, faster incremental builds, and a successful rollout.
AI-written summary · about
chapters (23)
- 0:00Introduction
- 0:50Speaker and project background
- 3:43reStructuredText vs Markdown
- 7:16Switching to Markdown
- 8:20Project documentation overview
- 10:04Migration planning
- 11:30MkDocs as tool
- 13:13Handling translations
- 14:36MkDocs plugins used
- 16:20Automating the reStructuredText to Markdown conversion
- 18:24Markdown validation tools
- 19:25Shared tooling project
- 20:28Migrating tutorials
- 21:10Migrating Toga API docs
- 23:36Migrating Briefcase docs
- 24:41Migrating Beware site
- 25:44Updating docs and templates
- 26:45Human aspects of migration
- 28:10Incremental changes
- 29:11Migration results
- 30:14Next steps
- 30:55MkDocs state and alternatives
- 31:38Resources and closing
related talks
35mSwitching from Sphinx to Markdown
42mTwo years of Markdoc: what we’ve learned about balancing developer and author experience
27mGoing from Publican to Read the Docs
40mFrom resistance to adoption: navigating the challenges of docs-like-code
27mPractical Sphinx
41mEmbracing the Kraken : How to build a docs-toolchain monster and why it’s OK
42mEngineering Documentation
35mBuilding Docs like Code: Continuous Integration for Documentation