Подтвердить что ты не робот

Как включить главную страницу в Sphinx TOC?

Предположим, что у меня есть проект Sphinx со следующими источниками:

index.rst
installation.rst
templating/
    index.rst
    module.rst
    fieldtype.rst

index.rst(домашняя страница) имеет следующее дерево TOC:

.. toctree::
   :titlesonly:

   installation
   templating/index

Я хочу, чтобы мой шаблон включал боковую панель, в которой перечислены все 3 страницы верхнего уровня (домашняя страница, установка, шаблон/индекс).

Я попытался добавить второе, скрытое дерево TOC на главной странице:

.. toctree::
   :hidden:

   index

.. toctree::
   :titlesonly:

   installation
   templating/index

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

Next up: <a href="{{ next.link }}">{{ next.title }}</a>

... всегда выводит ссылку главной страницы с домашней страницы. Нехорошо.

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

{% set homeClass = 'current' if pagename == 'index' else '' %}
<ul class="{{ homeClass }}">
    <li class="toctree-l1 {{ homeClass }}"><a class="{{ homeClass }} reference internal" href="/index.html">Home</a></li>
</ul>
{{ toctree() }}

Это также работает, за исключением того, что я не хочу принуждать документы к доступу на веб-сервере веб-сервера - я хочу, чтобы они также работали из файловой системы.

Я не могу просто установить URL-адрес в "index.html", потому что это не работает, когда youre в файле в шаблоне /.

Я пропустил что-то очевидное? Должен быть способ получить главную страницу в TOC, не разбивая ссылки next и динамический путь, который работает в локальной файловой системе, даже изнутри подпапок.

4b9b3361

Ответ 1

Оказалось, что ответ скрывался на видном месте на странице Sphinxs дерева TOC:

Имя специальной записи self означает документ, содержащий директиву toctree. Это полезно, если вы хотите сгенерировать "sitemap" из toctree.

Добавление self в дерево TOC отлично справилось! И если вы поместите его в отдельную, скрытую директиву toctree, она не будет отображаться в домашней странице оглавления:

.. toctree::
   :hidden:

   self


.. toctree::
   :titlesonly:

   installation
   templating/index

Ответ 2

Возможно ли, что вы переименуете страницу с исходным текстом проекта Sphinx, или, альтернативно, страницу шаблона/индекса? Переменная master_doc позволяет вам указать файл в вашем проекте, содержащий директиву root toctree, и его не нужно называть index.rst... в нашем проекте документации, чтобы обойти проблему очень похоже на это. a template/index.html, и наша корневая страница toctree на самом деле называется reference.rst.