html - 如何将 rel 属性添加到 HTML 输出中的 docutils sphinx 引用？

Question

我有一个 Sphinx 文档实用程序的简单扩展(我使用的版本是 Sphinx-1.1.3-py2.6)。很喜欢this Doug Hellmann 的优秀示例。如何添加 rel='bar' <a ...> 的最终 HTML 属性标签？

引用节点以这种方式创建:

node = nodes.reference(rawtext, utils.unescape(text),
            internal=False,
            refuri=ref,
            classes=['foocss'],
            rel='bar',
            **options)

然而，rel='bar'属性从最终的 HTML 标记中删除。通过源代码搜索让我找到了 sphinx/writers/html.py和 HTMLTranslator类(class)。这是 visit_reference 方法的一部分:

# overwritten
def visit_reference(self, node):
    atts = {'class': 'reference'}
    
    <snip>

    if 'reftitle' in node:
        atts['title'] = node['reftitle']
    self.body.append(self.starttag(node, 'a', '', **atts))

不处理其他属性。也许它们可以在其他部分被替换。在这方面我找不到任何有用的东西。

所以，我可以:

• 创建一个自定义节点，重新实现引用节点的所有功能。少量添加的工作相当多。
• 覆盖visit_reference sphinx/writers/html.py 中的方法.更快，但不利于 future 的 Sphinx 更新。
• 事后将 jQuery 的 rel 属性添加到链接标记。好吧，也不漂亮。

Answer 1

我设法用 download_reference 做到了这一点。使用 app.add_node 我覆盖了 visit_... 方法:

import posixpath
from sphinx.writers.html import HTMLTranslator
from sphinx.addnodes import download_reference

def visit_download_reference(self, node):
    if node.hasattr('filename'):
        self.body.append(
            '<a class="reference download internal" href="%s" %s>' %
            (posixpath.join(self.builder.dlpath, node['filename']), 'rel="%s"' % node['rel'] if node.get('rel', None) else ''))
        self.context.append('</a>')
    else:
        self.context.append('')

def setup(app):
    app.add_node(download_reference, html=(visit_download_reference, HTMLTranslator.depart_download_reference))

full extension is here