Как я могу ссылаться на раздел страницы в потоке sphinx

Ответ 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, чтобы стилировать заголовки по своему вкусу, а не скрывать их.

Ответ 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.