Python sphinx 使文档的标题级别自动依赖于深度'；s它们所属的（子（子（…））文件夹的级别_Python Sphinx_Restructuredtext_Sections_Toctree

Python sphinx 使文档的标题级别自动依赖于深度'；s它们所属的（子（子（…））文件夹的级别

python-sphinx

Python sphinx 使文档的标题级别自动依赖于深度'；s它们所属的（子（子（…））文件夹的级别,python-sphinx,restructuredtext,sections,toctree,Python Sphinx,Restructuredtext,Sections,Toctree,假设我有：我的sphinx doc源文件夹的根（source）处的foo0.rst文件 source的子文件夹subfolder1中的foo1.rst文件子文件夹1的子文件夹子文件夹2中的foo2.rst文件即: $ tree source source ├── foo0.rst └── subfolder1 ├── foo1.rst └── subfolder2 └── foo2.rst 全部内容相同： This a title ==========

假设我有：

我的
```
sphinx doc
```
源文件夹的根（
```
source
```
）处的
```
foo0.rst
```
文件
```
source
```
的子文件夹
```
subfolder1
```
中的
```
foo1.rst
```
文件
```
子文件夹1
```
的子文件夹
```
子文件夹2
```
中的
```
foo2.rst
```
文件

即:

$ tree source
source
├── foo0.rst
└── subfolder1
    ├── foo1.rst
    └── subfolder2
        └── foo2.rst

全部内容相同：

This a title
============

现在，如果

index.rst

包含：

Welcome to Test's documentation!
================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

生成html

提供：

Welcome to Test’s documentation!

Contents:

    • This a title
    • This a title
    • This a title

也就是说，所有的标题都是章节

我希望得到的是以下内容：

Welcome to Test’s documentation!

Contents:

    • This a title
      ◦ This a title
        ▪ This a title

Contents:

    • This a title (foo0)
      ◦ This a title (foo1)
        ▪ This a title (foo2)

这是：

```
foo0.rst
```
作为一个节
```
子文件夹1/foo1.rst
```
是子文件夹（而不是节）
```
subfolder1/subfolder2/foo2.rst
```
是一个子部分（而不是一节）

因此，我的问题是：是否有可能将属于（子（子（…））文件夹的文档自动依赖于

它们所属文件夹的深度级别？

应用于目录树的样式取决于您使用的文件夹。主题的CSS将对Sphinx翻译成

和

的条目应用一种样式，这取决于它们在给定的

目录树中的位置，以及您在单个.rst
文件中的组织方式
例如，检查Sphinx生成的HTML元素。toctree
将是一个div class=“toctree-wrapper composite”
，每个级别的节都被命名为
，然后
，等等
实现您想要的一种方法是使用将给定的目录树
包围起来。。类：：
指令（as）并应用。但这会影响任何其他.rst
文件的样式，您希望将其作为条目包含在该目录树中
在任何情况下，如果你重构你的项目，你将招致额外的工作和潜在的松散的自动化
另外，还可以将：hidden:
选项与指令一起使用。如果在可见的目录树
之前声明隐藏的目录树
，“文档层次结构”可以为您确定条目在层次结构中的位置。之后，不带：hidden:
选项的可见目录树将把.rst
文件条目呈现为在层次结构中具有固定位置的
元素。（可以看到一个彻底的例子）
这是可以做到的，但您将违反目录树的特性
普遍的解决方案是根据您希望目录树
的显示方式编写.rst
文件和节。（这种方法具有所有的优点，但唯一的缺点是限制了.rst
文件的编写方式）。这可能是比尝试调整CSS样式或使用变通方法更好的解决方案

编辑：
我以前写的是正确的，但可能太笼统了。因此，我将为该示例提供一个可能的解决方案。如果您需要以下内容：
Welcome to Test’s documentation!

Contents:

    • This a title
      ◦ This a title
        ▪ This a title

Contents:

    • This a title (foo0)
      ◦ This a title (foo1)
        ▪ This a title (foo2)

一个简单的选择是使用toctree
s链。如果不想看到文档层次结构中较低的目录树，则可以隐藏它们
index.rst

.. toctree::
   :maxdepth: 3

   foo0

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/foo1

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/subfolder2/foo2

在foo0.rst中
.. toctree::
   :maxdepth: 3

   foo0

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/foo1

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/subfolder2/foo2

在子文件夹1/foo1.rst中
.. toctree::
   :maxdepth: 3

   foo0

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/foo1

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/subfolder2/foo2

结果将与您指定的一样。
我的回答是，考虑生成HTML输出，而不是LaTeX…我不知道Sphinx如何将目录树转换为LaTeX。但是，如果目录树给你带来了太多的麻烦，最简单的解决方案仍然是构建一个reST项目符号列表，其中包含链接和交叉引用，你可以在其中完全按照自己的意愿构造级别。不，没有。@DenisBitouzé有几种可能的解决方案。最简单的方法是使用带有全局模式的目录树为每个目录添加1个.rst
，并将这些目录树链接到index.rst
中的目录树。文档中没有说明Sphinx是否会识别a，我试着看了看，但没能弄明白（我必须测试它）。@DenisBitouzé另一个解决方案——因为pandoc
给你一个目录树，里面有.rst
文件的完整列表——是为循环编写一个简单的（用任何语言）在这里，您可以将路径列表从.txt
转换为嵌套的路径列表，每个文件都有一个。然后使用目录树中的：hidden:
选项，只需复制引用的嵌套项目符号列表即可。@DenisBitouzé上述解决方案相对简单且省力。最好的解决方案取决于你的目标。您是否只想导出/迁移现有的wiki，而不需要在将来进行开发/重构？（Sphinx有许多应用程序，通常是记录正在开发的代码项目。）决定最佳操作方案取决于您将使用Sphinx项目的应用程序以及将文档部署到何处。（例如，在ReadTheDocs上，目录树被绑定到侧边栏上，因此您可能希望努力保存它。）我稍后将深入研究这些解决方案（现在太忙了）：谢谢！在某个时候，应该迁移并关闭DokuWiki
站点，这样将来就不会进行开发/重构。这个网站是一个LaTeX常见问题解答，应该部署在GitLab页面上。@DenisBitouzé是的，这正是我的意思。嵌套项目符号列表解决方案的优点是，如果您是从固定（非常大但完整）的链接列表生成链接，则可以通过编程轻松实现。（N可能有数千个，因此用1for
循环求解它可能不太可能