如何在Sphinx的toctree中链接到页面的某个部分

Question

我在sphinx页面中有一个.. toctree，其中包含指向我包中其他rst文件的相对链接。如何在链接中包含到给定页面的子标题，而不是整个页面本身？

我试着去......

.. toctree::

   page#section

但那没有起作用。任何帮助都很好。

- Duncan Macleod

Answer 1

经过多次尝试，我找到了以下解决方案，但首先需要说明我的目标是：

1. 标题不出现在内容正文中
2. 标题出现在目录中

因此，从目录链接到文档中任意但不可见的部分。

我需要这个功能来链接Sphinxcontrib PHPDomain生成的某些源代码文档中的方法 - 这些方法会自动生成自己的部分链接，但默认情况下不会添加到目录中。

步骤1：

在需要此链接功能的RST文件顶部添加一个新角色，如下所示：

.. role:: hidden
   :class: hidden

步骤2：

在内容中的某个位置，按如下方式使用此角色：

:hidden:`My Arbitrary Location`
"""""""""""""""""""""""""""""""

第三步：

向项目添加新的CSS（通常通过将CSS文件添加到_static中，或定义样式表等方式完成 - 参见此处）：

.rst-content .hidden {
    display: none;
}

nav .hidden {
    display: unset;
}

这将导致标题在内容中被隐藏，但在TOC中显示。

然后，在其他文档中根据需要重复使用该角色。

---

请注意，如果您的目标是链接到文档中的任意位置并仍然在内容中显示标题，只需更改CSS以使标题按您的喜好进行样式设置，而不是隐藏它们。

- Swader

Answer 2

在创建目录时，Sphinx会包括所有引用文件中的标题和副标题，并且深度不超过配置的树形结构深度。因此，您可以简单地不以标题开始页面，并在想要目录指向的位置插入标题，例如：

.. _my-rst-file:
**You can use bold print here if you want. This will not appear in the ToC**
.. rubric:: Or the "rubric" directive

And here some more text, normal font weight.

Here comes the heading that will appear in the ToC
""""""""""""""""""""""""""""""""""""""""""""""""""
And so on...

您需要像往常一样在目录中包含页面引用。 因此，在目录中，您应该有：

.. toctree::

   my_rst_file

在我们的例子中，生成的结果（HTML、PDF或其他）只会在目录中引用“这里是将出现在目录中的标题”。

- Timotheus.Kampik

---

您可以通过在目录中添加此行来实现相同的效果:你好世界 <my_rst_file> - Blundell