Sphinx extension to add a http role for docs.

This extension makes it easy to reference HTTP status codes.


To use this, you just need to add the extension in

extensions = [


.. http-status-codes-format::

Specifies a new format to use by default for any http roles. This should include %(code)s for the numeric code and %(name)s for the name of the HTTP status code.

Call this again without an argument to use the default format.


References an HTTP status code, expanding to the full status name and linking to documentation on the status in the process.



The format string used for the titles for HTTP status codes. This defaults to HTTP %(code)s %(format)s and can be temporarily overridden using http-status-codes-format.


The location of the docs for the status codes. This expects a string with a %s, which will be replaced by the numeric HTTP status code.


http_role(role, rawtext, text, linenum, inliner)

Implementation of the http role.


Set up the Sphinx extension.


SetStatusCodesFormatDirective(name, ...)

Specifies the format to use for the :http: role's text.

class beanbag_docutils.sphinx.ext.http_role.SetStatusCodesFormatDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Directive

Specifies the format to use for the :http: role’s text.

required_arguments = 0

Number of required directive arguments.

optional_arguments = 1

Number of optional arguments after the required arguments.

final_argument_whitespace = True

May the final argument contain whitespace?


Run the directive.


An empty list, always.

Return type:


beanbag_docutils.sphinx.ext.http_role.http_role(role, rawtext, text, linenum, inliner, options={}, content=[])

Implementation of the http role.

This is responsible for converting a HTTP status code to link pointing to the status documentation, with the full text for the status name.

  • rawtext (unicode) – The raw text for the entire role.

  • text (unicode) – The interpreted text content.

  • linenum (int) – The current line number.

  • inliner (docutils.parsers.rst.states.Inliner) – The inliner used for error reporting and document tree access.

  • options (dict) – Options passed for the role. This is unused.

  • content (list of unicode) – The list of strings containing content for the role directive. This is unused.


The result of the role. It’s a tuple containing two items:

  1. A single-item list with the resulting node.

  2. A single-item list with the error message (if any).

Return type:



Set up the Sphinx extension.

This registers the http role, http-status-codes-format directive, and the configuration settings for specifying the format and URL for linking to HTTP status codes.


app (sphinx.application.Sphinx) – The Sphinx application to register roles and configuration on.