sphinx-external-toc

一个允许在文档文件外部定义文档网站图（即目录）的Sphinx扩展。如Jupyter Book所使用！

在正常的Sphinx文档中，文档网站图是通过自下而上的方法定义的——在文档的页面中添加toctree指令。

此扩展促进了一个自上而下的方法来定义网站图结构，在一个单独的YAML文件中。

它还允许自动排除目录表中未指定的文档。

用户指南

Sphinx配置

添加到您的conf.py

extensions = ["sphinx_external_toc"]
external_toc_path = "_toc.yml"  # optional, default: _toc.yml
external_toc_exclude_missing = False  # optional, default: False

注意external_toc_path始终以Unix路径读取，可以是相对于源目录的指定（推荐）或绝对路径。

基本结构

一个最小的目录表定义了顶级root键，用于单个根文档文件

root: intro

root键的值将是文件路径，以Unix格式（文件夹用/分隔），相对于源目录，可以有或没有文件扩展名。

:::{note} 此根文件将设置为master_doc。 ::

文档文件可以有subtrees键 - 表示该文档的各个单独的目录表列表 - 并且每个子树应有一个entries键 - 表示子链接的列表，可以是以下之一

• file：单个文档文件的Unix格式路径，可以有或没有文件扩展名（与root相同）
• glob：一个或多个文档文件的路径 通过 Unix shell样式通配符（类似于fnmatch，但单个星号不匹配斜杠。）
• url：外部URL的路径（例如以http或https开头）

:::{important} 每个文档文件在目录表中只能出现一次！ ::

这可以递归到任何深度。

root: intro
subtrees:
- entries:
  - file: doc1
    subtrees:
    - entries:
      - file: doc2
        subtrees:
        - entries:
          - file: doc3
  - url: https://example.com
  - glob: subfolder/other*

这相当于在intro中有单个toctree指令，包含doc1，以及doc1中有一个单个toctree指令，具有:glob:标志并包含doc2，https://example.com和subfolder/other*。

作为一个简写，entries键可以与file处于同一级别，表示具有单个子树的文档。例如，此文件与上面的文件完全等价

root: intro
entries:
- file: doc1
  entries:
  - file: doc2
    entries:
    - file: doc3
- url: https://example.com
- glob: subfolder/other*

文件和URL标题

默认情况下，file文档内的第一个标题将被用作生成的目录表中的标题。使用title键，您可以设置文档的替代标题，也可以为url设置。

root: intro
subtrees:
- entries:
  - file: doc1
    title: Document 1 Title
  - url: https://example.com
    title: Example URL Title

目录树选项

每个子树都可以配置多个选项（参见sphinx toctree选项）

• caption（字符串）：子树的标题，例如在目录表中显示在子树上方
• hidden（布尔值）：是否在文档内（内联）显示目录表（默认为False）。默认情况下，它附加到文档末尾，但也可以参见tableofcontents指令以确定目录表的位置。
• maxdepth（整数）：显示文档内目录表时使用的最大嵌套深度（默认为-1，表示无限）。
• numbered（布尔值或整数）：自动为子树内的所有文档添加数字（默认为False）。如果设置为True，所有子树也将根据嵌套进行编号（例如，使用1.1或1.1.1），或者如果设置为整数，则仅应用于该深度。
• reversed（布尔值）：如果为True，则子树中的条目将按相反顺序列出（默认为False）。这在使用glob条目时可能很有用。
• titlesonly（布尔值）：如果为True，则仅在目录表中显示文档的第一个标题，而不是同一级别的其他标题（默认为False）。

这些选项可以在子树级别设置

root: intro
subtrees:
- caption: Subtree Caption
  hidden: False
  maxdepth: 1
  numbered: True
  reversed: False
  titlesonly: True
  entries:
  - file: doc1
    subtrees:
    - titlesonly: True
      entries:
      - file: doc2

或者，如果您正在使用单个子树的简写，则在options键下设置选项

root: intro
options:
  caption: Subtree Caption
  hidden: False
  maxdepth: 1
  numbered: True
  reversed: False
  titlesonly: True
entries:
- file: doc1
  options:
    titlesonly: True
  entries:
  - file: doc2

您还可以使用顶级defaults键，为所有子树设置默认选项

root: intro
defaults:
  titlesonly: True
options:
  caption: Subtree Caption
  hidden: False
  maxdepth: 1
  numbered: True
  reversed: False
entries:
- file: doc1
  entries:
  - file: doc2

默认情况下不应通常使用numbered，因为嵌套子树无法更改编号，Sphinx将会记录警告。 ::

注意：默认情况下，每个子树的标题编号会重新开始。如果您希望编号连续，请检查sphinx-multitoc-numbering 扩展。 ::

使用不同的键映射

对于某些用例，将subtrees/entries键映射到例如输出LaTeX结构可能会有所帮助。

可以使用format键提供此类映射（以及初始默认值）。目前可用

• jb-article:
  • 将entries映射到sections
  • 将titlesonly的默认值设置为true
• jb-book:
  • 将顶级subtrees映射到parts
  • 将顶级entries映射到chapters
  • 将其他层级的entries映射到sections
  • 将titlesonly的默认值设置为true

例如

defaults:
  titlesonly: true
root: index
subtrees:
- entries:
  - file: doc1
    entries:
    - file: doc2

等同于

format: jb-book
root: index
parts:
- chapters:
  - file: doc1
    sections:
    - file: doc2

重要提示：这些键名更改不会改变输出网站结构。 ::

在页面内容中添加目录

默认情况下，每个文档（每个子树一个）生成的toctree被附加到文档末尾并隐藏（例如，大多数HTML主题将它们显示在侧边栏中）。但是，如果您希望它们在文档体中的某个特定位置可见，您可以使用tableofcontents指令来实现。

ReStructuredText

.. tableofcontents::

MyST Markdown

```{tableofcontents}
```

当前，每个页面（所有toctree都添加到这里）只应使用一个tableofcontents，并且只有当它是带有子/后代文档的页面时才使用。

注意，这将覆盖为子树设置的hidden选项。

排除目录中不存在的文件

默认情况下，Sphinx将构建所有文档文件，无论它们是否在目录中指定，如果它们

1. 与加载的解析器相关的文件扩展名（例如.rst或.md）
2. 不匹配exclude_patterns中的模式

要将不匹配目录中的任何文件或glob的文档文件自动添加到exclude_patterns列表中，请将以下内容添加到您的conf.py

external_toc_exclude_missing = True

注意，出于性能考虑，即使未在目录中指定，位于隐藏文件夹（例如，在.tox或.venv中）的文件也不会添加到exclude_patterns中。您应该明确排除这些文件夹。

重要提示：此功能目前与孤儿文件不兼容。 ::

命令行

此软件包附带sphinx-etoc命令行程序，并提供了一些额外的工具。

查看所有选项

$ sphinx-etoc --help
Usage: sphinx-etoc [OPTIONS] COMMAND [ARGS]...

  Command-line for sphinx-external-toc.

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  from-project  Create a ToC file from a project directory.
  migrate    Migrate a ToC from a previous revision.
  parse      Parse a ToC file to a site-map YAML.
  to-project    Create a project directory from a ToC file.

仅从目录文件构建模板项目

$ sphinx-etoc to-project -p path/to/site -e rst path/to/_toc.yml

注意，您还可以在meta/create_files中添加额外的文件，并使用meta/create_append将文本追加到文件的末尾，例如。

root: intro
entries:
- glob: doc*
meta:
  create_append:
    intro: |
      This is some
      appended text
  create_files:
  - doc1
  - doc2
  - doc3

从现有网站构建目录文件

$ sphinx-etoc from-project path/to/folder

使用的一些规则

• 如果文件/文件夹与由-s添加的模式匹配（基于fnmatch Unix shell样式通配符），则会跳过这些文件/文件夹
• 跳过没有任何内容文件的子文件夹
• 文件和文件夹名称将按自然顺序排序
• 如果任何文件夹中有一个名为index（或由-i设置的名称）的文件，它将被视为索引文件，否则将使用排序后的第一个文件。

该命令还可以根据其路径为每个文件猜测一个title

• 对于索引文件，使用文件夹名称，否则使用文件名
• 使用_分隔单词
• 如果第一个“单词”是整数，则将其删除

例如，对于包含文件的

index.rst
1_a_title.rst
11_another_title.rst
.hidden_file.rst
.hidden_folder/index.rst
1_a_subfolder/index.rst
2_another_subfolder/index.rst
2_another_subfolder/other.rst
3_subfolder/1_no_index.rst
3_subfolder/2_no_index.rst
14_subfolder/index.rst
14_subfolder/subsubfolder/index.rst
14_subfolder/subsubfolder/other.rst

将创建目录

$ sphinx-etoc from-project path/to/folder -i index -s ".*" -e ".rst" -t
root: index
entries:
- file: 1_a_title
  title: A title
- file: 11_another_title
  title: Another title
- file: 1_a_subfolder/index
  title: A subfolder
- file: 2_another_subfolder/index
  title: Another subfolder
  entries:
  - file: 2_another_subfolder/other
    title: Other
- file: 3_subfolder/1_no_index
  title: No index
  entries:
  - file: 3_subfolder/2_no_index
    title: No index
- file: 14_subfolder/index
  title: Subfolder
  entries:
  - file: 14_subfolder/subsubfolder/index
    title: Subsubfolder
    entries:
    - file: 14_subfolder/subsubfolder/other
      title: Other

API

将目录文件解析为SiteMap，它是MutableMapping子类，键表示docnames，映射到包含其应包含的toctrees的Document

import yaml
from sphinx_external_toc.parsing import parse_toc_yaml
path = "path/to/_toc.yml"
site_map = parse_toc_yaml(path)
yaml.dump(site_map.as_json())

例如，将生成

root: intro
documents:
  doc1:
    docname: doc1
    subtrees: []
    title: null
  intro:
    docname: intro
    subtrees:
    - caption: Subtree Caption
      numbered: true
      reversed: false
      items:
      - doc1
      titlesonly: true
    title: null
meta: {}

开发说明

问题 / TODOs

• 添加额外的顶级键，例如appendices（见https://github.com/sphinx-doc/sphinx/issues/2502）和bibliography
• 使用external_toc_exclude_missing排除特定的文件后缀：目前如果您有文件doc.md和doc.rst，并将doc.md放入目录中，它将doc.rst添加到排除模式，但然后在查找doc.md时，仍会选择doc.rst（因为它在source_suffix中排在第一位）。也许可以在sphinx上提交一个问题，即doc2path应尊重排除模式。
• 将https://github.com/executablebooks/sphinx-multitoc-numbering集成到此扩展中？（或上游PR）
• 记录抑制警告
• 针对孤文件进行测试
• https://github.com/executablebooks/sphinx-book-theme/pull/304
• CLI命令用于从现有文档toctrees生成目录（然后删除toctree指令）
• 测试目录更改后的重建（并记录在目录更改时如何控制重建）
• 一些jupyter-book问题指出，基于文档中toctree的位置，编号可能存在潜在变化。因此，可以考虑将其放置在例如第一个标题/标题下。