如何链接到狮身人面像目录树中的页面部分答案

【问题标题】：How can I link to a page section in a sphinx toctree如何链接到狮身人面像目录树中的页面部分
【发布时间】：2013-11-10 07:13:03
【问题描述】：

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

我被刺了

.. toctree::

   page#section

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

【问题讨论】：

标签： python-sphinx sections toctree

【解决方案1】：

经过很多hacky，我得出了以下解决方案，但我首先应该声明我的目标是：

标题不会出现在内容正文中
让标题出现在目录中

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

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

第 1 步：

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

.. role:: hidden
   :class: hidden

第二步：

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

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

第 3 步：

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

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

nav .hidden {
    display: unset;
}

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

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

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

【讨论】：

【解决方案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。

【讨论】：