如何在 Sphinx 中正确定义新警告？

Question

使用 Sphinx 很容易编写扩展，但是很难以正确的方式扩展 Sphinx。

我想定义一个自定义警告，所以我有：

class exercise(nodes.Admonition, nodes.Element):
    pass

class ExerciseDirective(BaseAdmonition):
    node_class = exercise

def visit_exercise(self, node, name=''):
    self.visit_admonition(node, 'exercise')

def depart_exercise(self, node=None):
    self.depart_admonition(node)

def setup(app):
    app.add_directive('exercise', ExerciseDirective)

    app.add_node(exercise,
        html=(visit_exercise, depart_exercise)
    )

不幸的是，这还不够，因为我的 exercise 没有标题。我注意到警告的翻译在 docutils/languages 上，以后可以用 language.labels 阅读。由于我的标签 exercise 没有定义，所以我没有文字。

正确的方法是为定义的语言添加一个新标签。我不知道怎么....

一个非常丑陋的解决方案是破解硬编码admonitionlabels：

sphinx.locale.admonitionlabels['exercise'] = 'Exercise'

Answer 1

您也可以像基础 visit_admonition 那样手动添加标题节点：

def visit_exercise(self, node, name=''):
    self.visit_admonition(node, 'exercise')
    if not isinstance(node[0], nodes.title):
        node.insert(0, nodes.title('exercise', _('Exercise')))

我以 _('Exercise') 为例，但如果您不打算本地化，也可以只输入 'Exercise'。

如何在 Sphinx 中正确定义新警告？

How to properly define a new admonition in Sphinx?

python

docutils

python-sphinx