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 solution isn’t writing better docs. It’s automating the process so docs stay current without manual effort.

What this workshop covers

I recorded this workshop for PyCon APAC 2020. It walks through the tools and techniques for Docs as Code:

• GitHub - Host docs near source code

• reStructuredText - Write in plain text, not Word

• Sphinx - Generate sites automatically

• ReadTheDocs - Automate publishing

• Vale - Test docs like you test code

Why this approach works

Docs live with code. When code changes, docs are right there. Updating is part of the normal workflow, not an afterthought.

Automation handles the boring parts. Write in plain text, commit to Git, the site builds automatically. No manual publishing steps.

Testing catches issues. Vale checks style, broken links, and consistency. Same CI/CD pipeline that tests your code.

Next steps

Want to go deeper? Join the Write the Docs community - practitioners sharing what actually works.