python-sphinx - 如何链接到狮身人面像目录树中的页面部分

Question

我有一个.. toctree作为狮身人面像页面的一部分，其中包括指向rst我的包中其他文件的相对链接。如何包含指向给定页面的子部分的链接，而不是整个页面本身？

我试了一下

.. toctree::

   page#section

但这没有用。任何帮助都很棒。

Answer 1

经过一番骇客之后，我得出了以下解决方案，但我首先应该声明我的目标是：

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

所以基本上从 TOC 链接到文档的任意但不可见的部分。

我需要这个以便能够链接到使用 Sphinxcontrib PHPDomain 呈现的某些源代码文档中的方法 - 这些方法会生成它们自己的部分链接，但默认情况下不会添加到 TOC 中。

步骤1：

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

.. role:: hidden
   :class: hidden

第2步：

在内容的某处，使用此角色：

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

第 3 步：

将新的 CSS 添加到项目中（通常通过将 CSS 文件添加到_static中，或定义样式表或类似的东西来完成 - 请参阅此）：

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

nav .hidden {
    display: unset;
}

这会强制标题隐藏在内容中，但显示在目录中。

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

---

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

Answer 2

创建 ToC 时，Sphinx 会在配置的树深度内包含引用文件的所有标题和子标题。因此，您可以简单地不以标题开始页面并将标题插入您希望 ToC 指向的点，例如：

.. _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...

您需要像往常一样在 ToC 中包含页面参考。所以在 ToC 中，你有：

.. toctree::

   my_rst_file

在我们的示例中，构建结果（HTML、PDF 等）只会Here comes the heading that will appear in the ToC在 ToC 中引用。