python-sphinx - 是否可以用另一个指令替换一个指令

Question

我想创建一个替换(或类似的)，将一个指令转换为另一个。

例如:

在我们基于 sphinx 的文档中，我们使用 Admonitions创建某些注释和警告框。

但是，如果我们使用

.. note:: This is a Note

框的标题是Note，This is a Note成为第一段。

相比之下，这个指令

.. admonition:: This is a Note
   :class: note

生成一个带有所需标题的注释框。

为了让其他编辑更容易，我想创建一个替换，用第二个替换第一个。

有什么可以在 sphinx 中完成的吗？

Answer 1

是的，这是可以做到的。您必须向 Sphinx 添加自定义指令。使用以下内容创建一个 Python 模块(如 conf.py 旁边的 mydirectives.py):

import os
import os.path
import re
import subprocess

import docutils.core
import docutils.nodes
import docutils.parsers.rst

class AbstractDirective(docutils.parsers.rst.Directive):
    has_content = True
    required_arguments = 0
    optional_arguments = 0
    option_spec = {}
    final_argument_whitespace = False

    node_class = docutils.nodes.container

    def run(self):
        self.assert_has_content()
        text = '\n'.join(self.content)
        admonition_node = self.node_class(rawsource=text)
        self.state.nested_parse(self.content, self.content_offset,
                                admonition_node)
        admonition_node.set_class("abstract")
        return [admonition_node]


def setup(app):
    app.add_directive('abstract', AbstractDirective)

还必须有一些方法来添加标题。也许你需要添加一个标题节点自己。那里缺少文档，最好看看 source foradmonitions您将对文档有所了解。

使用自定义文本节点，您应该能够编写自己的注释指令。