Я использую sphinx, размещенный на https://readthedocs.org, для создания документации в форматах HTML и PDF. HTML работает отлично. PDF также создается успешно, но имеет проблему с вложенностью: я хотел бы, чтобы каждый из .rst документов верхнего уровня, связанных с моим оглавлением, был включен в PDF как "главы" верхнего уровня. Тем не менее, они на самом деле включены как подразделы, подчиненные содержанию титульной страницы index.rst. Вот что у меня есть в моем index.rst:
====
Blah
====
Welcome to the Blah project. It does various things.
Quickstart
==========
To download and install the Python package:
-------------------------------------------
* `python -m pip install Blah`
To run the demo:
----------------
* `python -m Blah --demo`
.. NEED SOME DIRECTIVE HERE
to tell sphinx/latex that Installation, BasicUsage
and friends are NOT subsections of "To run the demo"
but rather chapters at the same level as "Quickstart".
.. toctree::
:caption: Table of Contents
:maxdepth: 2
Installation
BasicUsage
AdvancedUsage
License
Indices and Tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
... и этот скриншот показывает, что я получаю в PDF:
... тогда как я хотел бы, чтобы «Как установить Blah» было главой 2, «Основное использование» - главой 3, и так далее. (HTML выглядит идеально организованным: целевая страница разделена на три заголовка раздела: Быстрый запуск , затем Содержание , затем Индексы и таблицы .)
Мой search-foo не помог мне найти способ рассказать сфинксу в контексте создания PDF-файлов: «go на два уровня здесь» или «закончить текущую главу здесь» (см. Комментарий) НЕОБХОДИМЫ НЕКОТОРЫЕ ДИРЕКТИВЫ ЗДЕСЬ "в списке index.rst выше). Это на самом деле возможно?
Содержимое одного из файлов главы, Installation.rst, выглядит следующим образом:
How to Install Blah
===================
It's on pypi.org so just use `pip`.
Другие файлы, BasicUsage.rst, AdvancedUsage.rst и License.rst могут быть для целей примера удален из to до c или сконструирован таким же образом: однострочный с заголовком = (тот же уровень подчеркивания, что и у «Quickstart» выше).