Sphinx Extension Learning – Jason H. Nicholson

This article is an aggregation of my notes about writing a Sphinx extension.

Definitions

builder: A class (inheriting from Builder) that takes parsed documents and performs an action on them. Normally, builders translate the documents to an output format, but it is also possible to use builders that check for broken links or coverage information.
directive: A rStructuredText markup element that allows marking a block of content with special meaning. Directes are supplied not only by docutils, but Sphinx and custom extension can add their own. The basic directive syntax looks like this:
```
.. directive-name:: argument ...
  :option-name: option-value

  Content of the directive.
```
domain: A domain is a collection of markup (reStructuredText directives and roles) to describe and link to objects belonging together, e.g. elements of a programming language. Directive and role names in a domain have names like domain:name, e.g. py:function. Having domains means that there are no namin problems when one set of documentation wants to refer to e.g. C++ and Python classes. It also means that extensions that support the documentation of whole new languages are much easier to write.
environment: A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents.
role: A reStructuredText markup element that allows marking a piece of text. Like directives, roles are extensible. The basic syntax looks like this:
```
:rolename:`content`
```

Introduction

Write the introduction here.

Main points

Add your first point.
Add your second point.
Add your third point.

Conclusion

Summarize the takeaway here.