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

  __firstlineno__ = 131
  __static_attributes__ = ()
  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.