From f96c51a0e7199134dfe6c80e10fc755ad873a4aa Mon Sep 17 00:00:00 2001
From: Michael Hanselmann <hansmi@google.com>
Date: Fri, 12 Aug 2011 14:05:35 +0200
Subject: [PATCH] sphinx_ext: Allow documenting opcode results
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Will be used by RAPI documentation.
Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: RenΓ© Nussbaumer <rn@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 8e4b4ccc8..2abfe6e0d 100644
--- a/lib/build/sphinx_ext.py
+++ b/lib/build/sphinx_ext.py
@@ -130,6 +130,23 @@ def _BuildOpcodeParams(op_id, include, exclude, alias):
yield " %s" % line
+def _BuildOpcodeResult(op_id):
+ """Build opcode result documentation.
+
+ @type op_id: string
+ @param op_id: Opcode ID
+
+ """
+ op_cls = opcodes.OP_MAPPING[op_id]
+
+ result_fn = getattr(op_cls, "OP_RESULT", None)
+
+ if not result_fn:
+ raise OpcodeError("Opcode '%s' has no result description" % op_id)
+
+ return "``%s``" % result_fn
+
+
class OpcodeParams(sphinx.util.compat.Directive):
"""Custom directive for opcode parameters.
@@ -161,6 +178,32 @@ class OpcodeParams(sphinx.util.compat.Directive):
return []
+class OpcodeResult(sphinx.util.compat.Directive):
+ """Custom directive for opcode result.
+
+ 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):
+ op_id = self.arguments[0]
+
+ tab_width = 2
+ path = op_id
+ include_text = _BuildOpcodeResult(op_id)
+
+ # Inject into state machine
+ include_lines = docutils.statemachine.string2lines(include_text, tab_width,
+ convert_whitespace=1)
+ self.state_machine.insert_input(include_lines, path)
+
+ return []
+
+
def PythonEvalRole(role, rawtext, text, lineno, inliner,
options={}, content=[]):
"""Custom role to evaluate Python expressions.
@@ -240,5 +283,6 @@ def setup(app):
"""
app.add_directive("opcode_params", OpcodeParams)
+ app.add_directive("opcode_result", OpcodeResult)
app.add_directive("pyassert", PythonAssert)
app.add_role("pyeval", PythonEvalRole)
--
GitLab