如何在 HTML 输出中将 rel 属性添加到 docutils sphinx 参考？答案

【问题标题】：How to add rel attribute to docutils sphinx reference in HTML output?如何在 HTML 输出中将 rel 属性添加到 docutils sphinx 参考？
【发布时间】：2012-10-21 13:06:28
【问题描述】：

我有一个 Sphinx 文档实用程序的简单扩展（我使用的版本是Sphinx-1.1.3-py2.6）。非常像 this Doug Hellmann 的优秀例子。如何在标签的最终 HTML 中添加 rel='bar' 属性？

似乎有几种方法可以做到这一点，但我找不到简单的方法。建议和提示表示赞赏。

参考节点以这种方式创建：

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

但是，rel='bar' 属性会从最终的 HTML 标记中删除。寻找源代码让我找到了 sphinx/writers/html.py 和 HTMLTranslator 类。这是 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))

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

所以，我可以：

创建一个自定义节点，重新实现参考节点的所有功能。少量添加就需要做相当多的工作。
覆盖 sphinx/writers/html.py 中的 *visit_reference* 方法。速度更快，但不利于未来的 Sphinx 更新。
事后将带有 jQuery 的 rel 属性添加到链接标签中。嗯，也不漂亮。

我确定我错过了明显而优雅的解决方案。

谢谢！

【问题讨论】：

我有同样的问题，认为你应该向 sphinx 提交补丁。但总的来说，我看到这个系统非常复杂和混乱。我花了 3 天时间研究，仍然无法理解如何在节点中获取 conf.py 参数。

标签： html hyperlink python-sphinx docutils

【解决方案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

【讨论】：