Question

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

我捅了一下

.. toctree::

   page#section

但那没用。任何帮助都很棒。

Answer 1

经过多次讨论之后，我来到了以下解决方案，但我首先要说明我的目标是：

标题未显示在内容正文中
标题出现在TOC

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

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

第1步：

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

.. role:: hidden
   :class: hidden

第2步：

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

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

第3步：

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

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

nav .hidden {
    display: unset;
}

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

然后，在其他文档中重用该角色。

请注意，如果你的目标是链接到文档中的任意位置并且仍然在内容中显示标题，只需更改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，等等）只会引用ToC中的Here comes the heading that will appear in the ToC。

如何链接到sphinx toctree中的页面部分

2 个答案: