是否应该转义自定义指令的参数？

Question

我为我的文档项目创建了一个自定义指令，该项目是使用 Sphinx 和 reStructuredText 构建的。该指令是这样使用的：

.. xpath-try:: //xpath[@expression="here"]

这会将 XPath 表达式呈现为一个简单的代码块，但会添加一个 link，用户可以单击它来针对示例 XML 文档执行表达式并查看匹配项(example link, example rendered page).

我的指令指定它没有内容，采用一个强制参数（xpath 表达式）并识别一对选项：

class XPathTryDirective(Directive):
    has_content = False
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'filename': directives.unchanged,
        'ns_args': directives.unchanged,
    }

    def run(self):
        xpath_expr = self.arguments[0]
        node = xpath_try(xpath_expr, xpath_expr)
        ...
        return [node]

一切似乎都完全按预期工作，除了如果 XPath 表达式包含 * 那么我的编辑器 (gVim) 中的语法突出显示真的搞砸了.如果我用反斜杠转义 *，那会让我的编辑器高兴，但反斜杠会出现在输出中。

我的问题是：

是否应该转义指令参数中的特殊字符？
如果是，指令 API 是否提供了获取未转义版本的方法？
或者它是否工作正常，唯一的问题是我的编辑器无法正确突出显示内容？

这似乎是一个小问题，但由于我一开始是新手，所以我发现突出显示非常有帮助。

Answer 1

Are special characters in an argument to a directive supposed to be escaped?

不，我认为没有对 rst 指令的参数执行额外的处理。这符合您的观察：无论您指定为指令的参数，您都可以通过 self.arguments[0].

直接获得

Or is it working fine and the only problem is my editor is failing to highlight things correctly?

是的，好像是这样。字符 * 首先用于 emphasis/italics，由于某种原因它在语法高亮期间得到更多关注。

这意味着此处的解决方案是调整或修复重组文本的 vim 语法文件。

是否应该转义自定义指令的参数？

Should arguments to a custom directive be escaped?

restructuredtext

python-sphinx