在 reStructuredText 中组合角色

Question

有没有办法在 reStructuredText 中组合标准文本角色？例如，要将字符串格式化为文字和强？

以下未达到我的预期：

**``text``**
``**text**``
:strong:`:literal:`text``
:literal:`:strong:`text``

Answer 1

不，这不是直接可能的。传递到实现角色的函数（参数 text）的内容不会被进一步解析。

见Creating reStructuredText Interpreted Text Roles。

就是说，您可以实现自己的 自己的第一个 角色，如果您愿意，它会通过 nested_parse() 进一步解析文本 - 但这不是您在这里要问的.

其他详细信息

docutils/docutils/parsers/rst/roles.py 的评论表明嵌套解析您所询问的 was/is planned/suggested 的功能，但还没有到目前为止实施。

# Once nested inline markup is implemented, this and other methods should
# recursively call inliner.nested_parse().

Answer 2

(以下特此发布CC0。)

如果您有能力扩展解析器（例如，如果您使用的是 Sphinx），则可以添加一个自定义角色来解析其内容。（请注意，这适用于简单的事情，例如 bold/italic 和替换，但如果您尝试嵌套角色或类似的疯狂行为，很可能会失败。

我用这个：

from docutils import nodes
from docutils.parsers.rst.states import Struct

def make_parsed_text_role(class_names=[], node_class=nodes.inline):
    def parsed_text_role(name, rawtext, text, lineno, inliner,
                         options={}, content=[]):
        # Prepare context for nested parsing
        memo = Struct(document=inliner.document,
                      reporter=inliner.reporter,
                      language=inliner.language)

        # Create parent node
        options['classes'] = class_names
        parent = node_class(rawtext, '', **options)

        # Parse role text for markup and add to parent
        processed, messages = inliner.parse(text, lineno, memo, parent)
        parent += processed

        # Return parent node, and any messages from nested parsing
        return [parent], messages

    return parsed_text_role

您可以像这样通过 Sphinx conf.py 使用它：

# Configuration file for the Sphinx documentation builder (conf.py).

project = 'My Documentation'
# ...

# ...paste the above code here...

def setup(app):
    app.add_role('foo', make_parsed_text_role(class_names=['foo']))

在您的文档中，您可以这样写：

This is :foo:`some **bold** text`!

在 HTML 中，这将产生一个 <span class="foo">，至少对于默认 nodes.inline 节点 class。生成器模式的使用是可选的，但如果您想制作一大堆这些自定义角色，它会非常方便。

在 reStructuredText 中组合角色

Composing roles in reStructuredText

restructuredtext

其他详细信息