Commit d59633a6 authored by Michael Hanselmann's avatar Michael Hanselmann
Browse files

sphinx_ext: New directive for supported methods



Until now many resources, but not all and not consistently list their
supported methods (e.g. “Supports the following commands: ``GET`` …”).
Not only is it easy for this list to get out of date, but it would also
be nice if it listed the required access permissions.

This patch adds a new directive to insert a table listing all supported
methods and their access permissions for a resource.
Signed-off-by: default avatarMichael Hanselmann <hansmi@google.com>
Reviewed-by: default avatarGuido Trotter <ultrotter@google.com>
parent aa82eb62
......@@ -570,6 +570,49 @@ class RapiAccessTable(s_compat.Directive):
return []
class RapiResourceDetails(s_compat.Directive):
"""Custom directive for RAPI resource details.
See also <http://docutils.sourceforge.net/docs/howto/rst-directives.html>.
"""
has_content = False
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = False
def run(self):
uri = self.arguments[0]
try:
handler = _RAPI_RESOURCES_FOR_DOCS[uri]
except KeyError:
raise self.error("Unknown resource URI '%s'" % uri)
lines = [
".. list-table::",
" :widths: 1 4",
" :header-rows: 1",
"",
" * - Method",
" - :ref:`Required permissions <rapi-users>`",
]
for method in _GetHandlerMethods(handler):
lines.extend([
" * - :ref:`%s <%s>`" % (method, _MakeRapiResourceLink(method, uri)),
" - %s" % _DescribeHandlerAccess(handler, method),
])
# Inject into state machine
include_lines = \
docutils.statemachine.string2lines("\n".join(lines), _TAB_WIDTH,
convert_whitespace=1)
self.state_machine.insert_input(include_lines, self.__class__.__name__)
return []
def setup(app):
"""Sphinx extension callback.
......@@ -580,6 +623,7 @@ def setup(app):
app.add_directive("pyassert", PythonAssert)
app.add_role("pyeval", PythonEvalRole)
app.add_directive("rapi_access_table", RapiAccessTable)
app.add_directive("rapi_resource_details", RapiResourceDetails)
app.add_config_value("enable_manpages", False, True)
app.add_role("manpage", _ManPageRole)
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment