在Sphinx中使用自定义HTML编写器

Question

我想知道怎么用一个不同的 HTMLTranslator，而不是Sphinx自带的那个，来自 sphinx.writers.html。

具体来说，我想修改一个叫 depart_desc_signature 的方法。我不能直接修改Sphinx，因为帮助文件是和其他人一起开发的，需要和标准的Sphinx正常编译。

我知道Sphinx支持：

• 扩展模块：http://sphinx-doc.org/ext/appapi.html
• 自定义构建器：http://sphinx-doc.org/ext/builderapi.html

Answer 1

在 conf.py 文件中定义一个 html_translator_class 来指定一个 HTML 转换器。

比如说，

html_translator_class = 'html2.HTMLTranslator'

不过，这样做和 mathjax 不是很兼容，所以如果 html2 只是简单复制了 sphinx.writers.html，你需要在 HTMLTranslator 中明确添加 mathjax 的调用：

def visit_displaymath(self, node):
    import sphinx.ext.mathjax
    sphinx.ext.mathjax.html_visit_displaymath(self, node)
def depart_displaymath(self, node):
    return
def visit_math(self, node):
    import sphinx.ext.mathjax
    sphinx.ext.mathjax.html_visit_math(self, node)
def depart_math(self, node):
    return

Answer 2

这个选中的答案在最近版本的Sphinx中已经不再适用了。我在sphinx-users邮件列表上询问了这个问题，Jean Abou Samra很友好地给我提供了以下解释和示例代码，这些代码可以放在conf.py文件中：

在配置文件中的setup()函数可以接收应用程序对象，并对其进行修改。比如，下面这段代码放在conf.py中，就会把所有的强调标记都解释为粗体：

from sphinx.writers.html import HTMLTranslator

class MyTranslator(HTMLTranslator):
     def visit_emphasis(self, node):
         self.visit_strong(node)
     def depart_emphasis(self, node):
         self.depart_strong(node)

def setup(app):
     app.set_translator('html', MyTranslator)