使用角色和指令扩展语法¶
概述¶
reStructuredText 和 MyST 的语法可以通过创建新的 **指令**(用于块级元素)和 **角色**(用于内联元素)来扩展。
在本教程中,我们将扩展 Sphinx 以添加
一个
hello
角色,它将简单地输出文本Hello {text}!
。一个
hello
指令,它将简单地输出文本Hello {text}!
作为一段。
对于此扩展,您需要了解一些 Python 的基本知识,我们还将介绍 docutils API 的一些方面。
设置项目¶
您可以使用现有的 Sphinx 项目,也可以使用 sphinx-quickstart 创建一个新项目。
有了它,我们将扩展添加到项目中,位于 source
文件夹中
在
source
中创建一个_ext
文件夹在
_ext
文件夹中创建一个名为helloworld.py
的新 Python 文件
以下是一个您可能获得的文件夹结构示例
└── source
├── _ext
│ └── helloworld.py
├── conf.py
├── index.rst
编写扩展¶
打开 helloworld.py
并将以下代码粘贴到其中
1from __future__ import annotations
2
3from docutils import nodes
4
5from sphinx.application import Sphinx
6from sphinx.util.docutils import SphinxDirective, SphinxRole
7from sphinx.util.typing import ExtensionMetadata
8
9
10class HelloRole(SphinxRole):
11 """A role to say hello!"""
12
13 def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
14 node = nodes.inline(text=f'Hello {self.text}!')
15 return [node], []
16
17
18class HelloDirective(SphinxDirective):
19 """A directive to say hello!"""
20
21 required_arguments = 1
22
23 def run(self) -> list[nodes.Node]:
24 paragraph_node = nodes.paragraph(text=f'hello {self.arguments[0]}!')
25 return [paragraph_node]
26
27
28def setup(app: Sphinx) -> ExtensionMetadata:
29 app.add_role('hello', HelloRole())
30 app.add_directive('hello', HelloDirective)
31
32 return {
33 'version': '0.1',
34 'parallel_read_safe': True,
35 'parallel_write_safe': True,
36 }
在此示例中发生了一些重要的事情
角色类¶
我们的新角色在 HelloRole
类中声明。
1class HelloRole(SphinxRole):
2 """A role to say hello!"""
3
4 def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
5 node = nodes.inline(text=f'Hello {self.text}!')
6 return [node], []
此类扩展了 SphinxRole
类。该类包含一个 run
方法,这是每个角色的必要条件。它包含角色的主要逻辑,并返回一个元组,其中包含
一个要由 Sphinx 处理的内联级 docutils 节点列表。
一个(可选的)系统消息节点列表
指令类¶
我们的新指令在 HelloDirective
类中声明。
1class HelloDirective(SphinxDirective):
2 """A directive to say hello!"""
3
4 required_arguments = 1
5
6 def run(self) -> list[nodes.Node]:
7 paragraph_node = nodes.paragraph(text=f'hello {self.arguments[0]}!')
8 return [paragraph_node]
此类扩展了 SphinxDirective
类。该类包含一个 run
方法,这是每个指令的必要条件。它包含指令的主要逻辑,并返回一个要由 Sphinx 处理的块级 docutils 节点列表。它还包含一个 required_arguments
属性,它告诉 Sphinx 指令需要多少个参数。
什么是 docutils 节点?¶
当 Sphinx 解析文档时,它会创建一个节点的“抽象语法树”(AST),这些节点以结构化的方式表示文档的内容,通常独立于任何一个输入(rST、MyST 等)或输出(HTML、LaTeX 等)格式。它是一棵树,因为每个节点都可以有子节点,依此类推。
<document>
<paragraph>
<text>
Hello world!
docutils 包提供了许多 内置节点,用于表示不同类型的内容,例如文本、段落、引用、表格等。
每个节点类型通常只接受一组特定的直接子节点,例如 document
节点应该只包含“块级”节点,例如 paragraph
、section
、table
等,而 paragraph
节点应该只包含“内联级”节点,例如 text
、emphasis
、strong
等。
the setup
函数¶
此函数是必需的。我们用它将我们的新指令插入到 Sphinx 中。
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_role('hello', HelloRole())
app.add_directive('hello', HelloDirective)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
您可以做的最简单的事情是调用 Sphinx.add_role()
和 Sphinx.add_directive()
方法,这就是我们在这里所做的。对于此特定调用,第一个参数是角色/指令本身的名称,如在 reStructuredText 文件中使用的那样。在本例中,我们将使用 hello
。例如
Some intro text here...
.. hello:: world
Some text with a :hello:`world` role.
我们还返回 扩展元数据,它指示扩展的版本,以及安全地将扩展用于并行读取和写入的事实。
使用扩展¶
必须在您的 conf.py
文件中声明扩展,以便 Sphinx 了解它。这里需要两个步骤
使用
sys.path.append
将_ext
目录添加到 Python 路径。这应该放在文件顶部。更新或创建
extensions
列表并将扩展文件名添加到列表中
例如
import os
import sys
sys.path.append(os.path.abspath("./_ext"))
extensions = ['helloworld']
您现在可以在文件中使用扩展。例如
Some intro text here...
.. hello:: world
Some text with a :hello:`world` role.
上面的示例将生成
Some intro text here...
Hello world!
Some text with a hello world! role.
进一步阅读¶
这是创建新角色和指令的扩展的最基本原理。
有关更高级的示例,请参阅 扩展构建过程。
如果您希望在多个项目或与他人共享您的扩展,请查看 第三方扩展 部分。