A practical introduction to Documentation as Code

Workshop: How to automate docs with GitHub, Sphinx, ReadTheDocs, and Vale

Documentation becomes outdated. Code changes. The docs don’t.

The fix isn’t writing better docs. It’s treating docs like code: version-controlled, automatically built, and tested in CI.

What this workshop covers

I recorded this workshop for PyCon APAC 2020. It walks through a full docs-as-code setup:

• GitHub to host docs next to source code

• reStructuredText to write in plain text instead of Word or Confluence

• Sphinx to generate a documentation site from those files

• ReadTheDocs to build and publish automatically on every commit

• Vale to lint your docs the same way you lint your code (style, consistency, broken links)

By the end, you have a pipeline: write in plain text, commit to Git, site builds and deploys automatically. No manual publishing steps.

Why bother

Docs live with code. When a developer changes an API, the docs are right there in the same repository. Updating them becomes part of the normal workflow, not a separate task someone forgets about.

Testing catches issues before users do. Vale flags inconsistent terminology, passive voice, broken links. Same CI pipeline that runs your unit tests.

And you own everything. Plain text files in Git. No vendor lock-in, no proprietary formats, no export headaches.

Go deeper

The Write the Docs community is the best place to learn from practitioners who actually do this. Worth joining if you’re serious about docs-as-code.