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 usinghttp-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
|
Implementation of the |
|
Set up the Sphinx extension. |
Classes
|
Specifies the format to use for the |
- 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?
- 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
ofunicode
) – 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:
A single-item list with the resulting node.
A single-item list with the error message (if any).
- Return type:
- 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.