From d59633a6a8216d77f1932a8851ba1406422fa2ea Mon Sep 17 00:00:00 2001
From: Michael Hanselmann <hansmi@google.com>
Date: Fri, 22 Feb 2013 15:18:56 +0100
Subject: [PATCH] sphinx_ext: New directive for supported methods
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
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: Michael Hanselmann <hansmi@google.com>
Reviewed-by: Guido Trotter <ultrotter@google.com>
---
lib/build/sphinx_ext.py | 44 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 44 insertions(+)
diff --git a/lib/build/sphinx_ext.py b/lib/build/sphinx_ext.py
index b3ef049a7..58d7cc5d5 100644
--- a/lib/build/sphinx_ext.py
+++ b/lib/build/sphinx_ext.py
@@ -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)
--
GitLab