Sunday 1:50 p.m.–2:20 p.m.
See Docs Run. Run, Docs, Run!
Catherine Devlin
- Audience level:
- Intermediate
- Category:
- Education
Description
Code executes. Docs just sit there looking pretty. Now it's time to blur that boundary! Tools like the IPython Notebook, Sphinx, dexy, and old-fashioned doctests blend code with docs, making package docs, educational materials, and system-level docs more engaging, relevant, and trustworthy.
Abstract
To be useful and trustworthy, specifications and tests need to exist as executable code, not just as documents for human reading. That realization has begun to spread to the field of documentation as well.
Doctests were possibly the first prominent Python technology to blur the boundary between documentation and executable code. In recent years, several other technologies have arisen, including
- the `doctest` and `autorun` extensions, which insert code execution results into Sphinx documents
- `Dexy`, which generates rich documents in virtually any format from templates that combine documentation and code
- the IPython Notebook, which combines a full Python client with rich webpage display and Markdown-based documentation
I'll explain the problems solved by executable documentation, then introduce the audience briefly to each of these types of technologies and explain what kinds of documentation each is suitable for.