Добавление подразделов self в оглавление

Question

У меня возникла проблема с получением оглавления (TOC) для отображения подразделов первой страницы моей документации.

У меня есть несколько разделов на моей первой странице, и я хотел бы, чтобы они отображались в оглавлении. Отображение подраздела отлично работает для всех остальных страниц, включенных в оглавление, но не для себя.

мой index.rst код:

=====
Title
=====

Subsection
----------

Some documentation.

Contents
--------

.. toctree::
   :maxdepth: 2

   self
   development

То, что я ожидал увидеть в оглавлении:

• заглавие
  • подсекция
  • содержание
• развитие
  • подсекция

Вместо этого я получаю следующее:

• заглавие
• развитие
  • подсекция

Пока я нашел одно решение, но оно не совсем удовлетворительное. Я могу поместить все содержимое на отдельной странице, а затем включить содержимое в index.rst используя .. include: директива, и поместите отдельную страницу в оглавление. Это заставляет оглавление выглядеть правильно, но создает дублирующую страницу, которая теперь включена в навигацию (предыдущая / следующая страница).

Answer 1

Вы можете использовать директиву TOC из reStructuredText напрямую:

.. contents::

См. http://docutils.sourceforge.net/docs/ref/rst/directives.html.

Answer 2

В вопросе есть несколько проблем с макетом раздела:

Вместо этого я получаю следующее:

• заглавие
• Развитие
  • Подраздел

С помощью selfпоскольку запись toctree делает заголовок самого внешнего раздела содержащего .rstфайл должен быть включен в эту строку записи toctree. В selfentry не будет отображать подразделы или родственные разделы, только заголовок самого внешнего раздела. Это противоречит обычным свойствам записей toctree.

Два результирующих следствия из вышеизложенного можно сразу заметить в примере из вопроса:

• title и developmentнеправильно отображаются как находящиеся на одном уровне в иерархии разделов. Когда .rst файл включен в toctree, его разделы в иерархии разделов располагаются ниже раздела, в котором объявлена ​​директива toctree.

• title будет повторяться дважды, как на разных уровнях, если содержащий .rst помещается во внешнее дерево.

Соответствующий title.rst:

       =====
Title
=====

Subsection
----------

Some documentation.

Contents
--------

.. toctree::
   :maxdepth: 2

   self
   development

Соответствующий development.rst:

       development
===========

some text

Subsection inside development.rst
---------------------------------

Соответствующий external.rst:

       Exterior
========

.. toctree::
    :maxdepth: 4

    title

---

---

Не следует стремиться к структуре разделов, которая противоречит свойствам директивы toctree. Из спецификации вопроса, самым простым и концептуально разумным решением является использование contentsдиректива для перечисления разделов в одном заданном .rst документ.

Я ожидал увидеть в оглавлении следующее:

• заглавие
  • Подраздел
  • Содержание
• Развитие
  • Подраздел

Самый простой вариант - использовать отдельные файлы title.rst и development.rst поместив их на один уровень в index.rst toctree.

Соответствующий index.rst:

       Exterior
========

.. toctree::

    title
    development

---

---

Чтобы создать дерево ссылок как внутренних, так и внешних по отношению к данному .rstфайл наилучшее решение состоит в использовании простой маркированный список из гиперссылок целей.

Соответствующий title.rst:

       .. _target_title:

=====
Title
=====

.. _target_subsection_title:

Subsection inside title.rst
---------------------------

Some documentation.

.. _target_contents:

Contents
--------

text

- :ref:`Title <target_title>`

 - :ref:`Subsection <target_subsection_title>`

 - :ref:`Contents <target_contents>`

- :ref:`Development <target_development>`

 - :ref:`Subsection <target_subsection_development>`

Соответствующий development.rst:

       .. _target_development:

development
===========

some text

.. _target_subsection_development:

Subsection inside development.rst
---------------------------------

Соответствующий external.rst:

       Exterior
========

.. toctree::
    :maxdepth: 4

    title
    development

---

---

затем включите содержимое в index.rst с помощью директивы.. include:

Использование .. include:: Директива только изменит место проблем с токтрием, не решив их полностью.