Блог

У меня есть .. toctree как часть страницы sphinx, которая включает относительные ссылки на другие rst файлы в моем пакете. Как я могу включить ссылку на подраздел данной страницы, а не на всю страницу?

Я попытался

 .. toctree::

   page#section
  

Но это не сработало. Любая помощь — это здорово.

После долгих взломов я пришел к следующему решению, но сначала я должен заявить, что моей целью было:

1. заголовок НЕ отображается в теле содержимого
2. должен ли заголовок отображаться в TOC

Таким образом, в основном ссылка из TOC на произвольную, но невидимую часть документа.

Мне это было нужно для того, чтобы иметь возможность ссылаться на методы в некоторой документации исходного кода, отображаемой с помощью Sphinxcontrib PHPDomain — эти методы генерируют собственные ссылки на разделы, но по умолчанию не добавляются в TOC.

Шаг 1:

В верхней части вашего ПЕРВОГО файла, для которого требуется эта функция связывания, добавьте новую роль как таковую:

 .. role:: hidden
   :class: hidden
  

Шаг 2:

Где-нибудь в содержимом используйте эту роль как таковую:

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

Шаг 3:

Добавьте новый CSS в проект (обычно это делается путем добавления файла CSS _static или определения таблицы стилей или чего-то подобного — см. Это):

 .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 у вас есть:

 .. toctree::

   my_rst_file
  

В нашем примере результат сборки (HTML, PDF, что угодно) будет иметь ссылку только Here comes the heading that will appear in the ToC в ToC.