Change the future

Friday 12:10 p.m.–12:40 p.m.

Better Documentation Through Automation: Creating Sphinx Extensions

Doug Hellmann

Audience level:
Novice
Category:
Documentation

Description

Sphinx is an incredibly useful tool for creating attractive documentation for your project, but if all you ever use it for is converting reStructuredText files to HTML you are barely scratching the surface of its power. This presentation shows how easy it is to extend Sphinx by defining new markup processors, allowing you to take your documentation to the next level.

Abstract

At some point after adopting Sphinx for documenting your project, you will undoubtedly find yourself running into limitations of the baseline version of the tool. Whether you are chafing at repeating yourself every time you link to your project site, frustrated by creating table content manually, or you simply want to produce something other than HTML output, this presentation will demystify Sphinx extensions and show you how to eliminate the friction from your documentation processes.

  • Don't Repeat Yourself
  • Using replacement text in reStructuredText
  • Syntax
  • rst_epilog
  • Defining a custom role for macros "with arguments"
  • Role syntax
  • Role processor function
  • docutils' parse tree
  • Sphinx configuration settings
  • Extended Automation Directives
  • Defining a directive
  • Processing arguments
  • Processing the body
  • Parsing reST recursively
  • Using your own syntax
  • Replacing parse nodes
  • Beyond HTML and PDF: Custom Builders
  • How Sphinx invokes a builder
  • Builder API methods
  • A spelling checker
  • Processing the nodes in a parse tree
  • Filtering on node type
  • Communicating with the user
  • Setting application exit code

Sponsors