python-sphinx - 如何配置用于 :menuselection:? 的分隔符

Question

我正在使用 Sphinx 为我的项目生成 HTML 文档。在行内标记下，Sphinx 文档讨论了 :menuselection:使用如下标记标记一系列菜单选择:

:menuselection:`Start --> Programs`

这会产生以下 HTML:

<span class="menuselection">Start ‣ Programs</span>

即--> 被转换为小三角形，我确定它是 U+2023，TRIANGULAR BULLET。

一切都很好，但我想使用不同的字符而不是三角形。我已经在 Sphinx 包和主题包 (sphinx-bootstrap-theme) 中详尽地搜索了“menuselection”、三角形字符和其他一些东西，但还没有找到任何可以从 进行替换的东西- -> 到 ‣ (无论如何对我来说没什么明显的)。但是一定有什么东西在我的 .rst 源和 html 之间转换它。

我的问题是:什么，具体是在做转换(sphinx core？HTML writer？Theme JS？)？

Answer 1

转换在 sphinx.roles.menusel_role() 函数中完成。您可以使用不同的分隔符创建您自己的此函数版本并注册以供使用。

将以下内容添加到项目的 conf.py 中:

from docutils import nodes, utils
from docutils.parsers.rst import roles
from sphinx.roles import _amp_re

def patched_menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    text = utils.unescape(text)
    if typ == 'menuselection':
        text = text.replace('-->', u'\N{RIGHTWARDS ARROW}')  # Here is the patch 
    spans = _amp_re.split(text)  

    node = nodes.emphasis(rawtext=rawtext)
    for i, span in enumerate(spans):
        span = span.replace('&&', '&')
        if i == 0:
            if len(span) > 0:
                textnode = nodes.Text(span)
                node += textnode
            continue
        accel_node = nodes.inline()
        letter_node = nodes.Text(span[0])
        accel_node += letter_node
        accel_node['classes'].append('accelerator')
        node += accel_node
        textnode = nodes.Text(span[1:])
        node += textnode

    node['classes'].append(typ)
    return [node], []

# Use 'patched_menusel_role' function for processing the 'menuselection' role
roles.register_local_role("menuselection", patched_menusel_role)

构建 html 时，请确保先make clean，以便使用补丁重新解析更新后的 conf.py。