You need to enable JavaScript to run this app.
优惠活动
大模型
产品
解决方案
定价
更多

如何在Sphinx reStructuredText中实现自动多级列表编号?

问题描述

我有一段手动编号的待办列表内容:

1. Do something #1

    1.1 Do something #2

        1.1.1 Do something #3

核心需求是最终输出为单文档(方便后续PDF打印),且标题之间可能插入正文内容。尝试了两种方案都存在问题:

  • 使用toctree:仅能提取第三方文件的标题,且会以独立文档页面链接的形式展示,不符合单文档要求
  • 使用content:由于该功能与标题层级强绑定,导致本地章节无法正常生成编号
解决方案

针对该场景,可通过以下方式满足需求:

  1. 启用自动章节编号:在项目的conf.py中配置自动编号规则,替代手动编号,避免层级冲突
    numfig = True
    numfig_format = {'section': '%s.'}
    
    Sphinx会根据标题层级自动生成规范编号,无需手动维护,且不影响标题间插入正文内容。
  2. 嵌入第三方文件内容:若需要引用第三方文件的标题并整合到单文档,放弃toctree,改用include指令将第三方文件内容直接嵌入当前文档
    .. include:: path/to/target_file.rst
    
    嵌入的内容会完全融入当前文档结构,保持单文档属性,同时自动继承章节编号规则。
  3. 规范手动列表样式:如果必须保留手动编号的待办列表结构,使用Sphinx的enumerate列表指令替代纯文本手动编号
    .. enumerate::
       :start: 1
    
       Do something #1
    
       .. enumerate::
          :start: 1
    
          Do something #2
    
          .. enumerate::
             :start: 1
    
             Do something #3
    
    这种方式既保留了层级编号的样式,又能与文档其他内容兼容,不影响PDF打印的单文档输出。

内容的提问来源于stack exchange,提问作者T4ASICK

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.07.15 11:16:09