У меня есть .. toctree как часть страницы sphinx, которая включает относительные ссылки на другие rst файлы в моем пакете. Как включить ссылку на подраздел данной страницы, а не на полную страницу?
Я сделал удар в
.. toctree::
page#section
Но это не сработало. Любая помощь велика.
После многих хакеров я пришел к следующему решению, но сначала должен указать, что моя цель состояла в следующем:
Таким образом, в основном, ссылка из 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, чтобы стилировать заголовки по своему вкусу, а не скрывать их.
При создании 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.