beanbag_docutils.sphinx.ext.http_role

Sphinx extension to add a http role for docs.

This extension makes it easy to reference HTTP status codes.

Setup

To use this, you just need to add the extension in conf.py:

extensions = [
    ...
    'beanbag_docutils.sphinx.ext.http_role',
    ...
]

Roles

.. 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.

:http:

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

Configuration

http_status_codes_format

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.

http_status_codes_url

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.

Functions

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

Implementation of the http role.

setup(app)

Set up the Sphinx extension.

Classes

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.

final_argument_whitespace = True

May the final argument contain whitespace?

optional_arguments = 1

Number of optional arguments after the required arguments.

required_arguments = 0

Number of required directive arguments.

run()

Run the directive.

Returns:

An empty list, always.

Return type:

list

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.

Parameters:

  • 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.

Returns:

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:

tuple

beanbag_docutils.sphinx.ext.http_role.setup(app)

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.

Parameters:

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