如何在Sphinx(reStructuredText)中实现自定义配色带编号的admonition
实现方案
第一步:修改conf.py注册自定义指令与编号逻辑
在你的项目conf.py末尾添加如下代码,这段代码会注册definition、theorem、example三类自定义admonition指令,同时实现按章节层级的连续编号逻辑:
from docutils import nodes from docutils.parsers.rst import Directive, directives from sphinx.util.docutils import SphinxDirective from sphinx import addnodes # 全局计数器,按章节存储当前编号 admonition_counter = {} class CustomNumberedAdmonition(SphinxDirective): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True has_content = True option_spec = { 'class': directives.class_option, 'name': directives.unchanged, } def run(self): # 获取当前章节的层级编号 env = self.env docname = env.docname # 获取当前章节的编号字符串,如3.2.1 section_num = env.toc_secnumbers.get(docname, {}).get(self.lineno, '') if not section_num: # 适配不同层级的章节编号获取 for secinfo in env.toc_secnumbers.get(docname, {}).values(): section_num = '.'.join(map(str, secinfo)) break # 按章节维护连续计数器 if section_num not in admonition_counter: admonition_counter[section_num] = 0 admonition_counter[section_num] += 1 current_num = f"{section_num}.{admonition_counter[section_num]}" # 生成admonition节点 admonition_node = nodes.admonition() admonition_node['classes'].append(self.name) title_text = f"{current_num} {self.name.capitalize()}: {self.arguments[0]}" title_node = nodes.title(text=title_text) admonition_node += title_node # 解析内容 self.state.nested_parse(self.content, self.content_offset, admonition_node) return [admonition_node] def setup(app): # 注册三类自定义指令,可根据需要扩展更多类型 app.add_directive('definition', CustomNumberedAdmonition) app.add_directive('theorem', CustomNumberedAdmonition) app.add_directive('example', CustomNumberedAdmonition) # 引入自定义样式,Sphinx 4.0+ 请替换为 add_css_file app.add_stylesheet('custom.css') # 每次构建前清空计数器 def reset_counter(app, docname): admonition_counter.clear() app.connect('builder-inited', reset_counter)
第二步:编写custom.css配置配色样式
在你项目的_static目录下创建custom.css文件,添加如下样式,可根据需求调整配色值:
/* 公共自定义admonition样式 */ .admonition { border-radius: 4px; padding: 12px; margin: 16px 0; } .admonition .admonition-title { font-weight: bold; margin-top: 0; margin-bottom: 8px; } /* 定义类蓝色样式 */ .admonition.definition { border-left: 4px solid #2196F3; background-color: #E3F2FD; } .admonition.definition .admonition-title { color: #1976D2; } /* 定理类绿色样式 */ .admonition.theorem { border-left: 4px solid #4CAF50; background-color: #E8F5E9; } .admonition.theorem .admonition-title { color: #388E3C; } /* 示例类橙色样式 */ .admonition.example { border-left: 4px solid #FF9800; background-color: #FFF3E0; } .admonition.example .admonition-title { color: #F57C00; }
第三步:使用测试
在你的rst文档中按你预期的语法编写即可:
Chapter ======= .. definition:: My name of choice My definition here. .. theorem:: my name of choice My theorem here.
在3.2.1小节下编写以上内容时,会自动渲染为编号3.2.1.1 Definition: My name of choice和3.2.1.2 Theorem: my name of choice的带配色admonition,和你预期的效果一致。
内容的提问来源于stack exchange,提问作者Hulda Hvönn
相关产品推荐
相关产品推荐

