Как я могу заставить сфинкса закончить главу при создании pdf?

Я использую 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:

скриншот pdf, показывающий чрезмерную вложенность

... тогда как я хотел бы, чтобы «Как установить Blah» был главой 2, «Основное использование» - главой 3 и так далее. (HTML выглядит идеально организованным: целевая страница разделена на три раздела: Быстрый старт, затем Оглавление, затем Указатели и таблицы. )

Мой search-foo не смог найти способ сказать sphinx в контексте создания PDF-файлов: «поднимитесь на два уровня здесь» или «здесь завершите текущую главу» (см. комментарий «ЗДЕСЬ НЕОБХОДИМА ДИРЕКТИВА» в index.rst список выше). Возможно ли это на самом деле?

Содержимое одного из файлов глав, Installation.rst, следующее:

How to Install Blah
===================

It's on pypi.org so just use `pip`.

Другие файлы, BasicUsage.rst, AdvancedUsage.rst и License.rst, могут быть либо удалены из оглавления для целей примера, либо созданы таким же образом: однострочный текст с подчеркнутым заголовком = (тот же уровень подчеркивания, что и у "Quickstart" выше). ).


python-sphinx read-the-docs pdflatex restructuredtext latexmk
person jez    schedule 26.03.2020    source источник
comment
Вы можете вставить новый заголовок раздела Table of Contents с символом подчеркивания === чуть выше вашего toctree.   -  person Steve Piercy    schedule 27.03.2020
comment
Это улучшит ситуацию, но незначительно. Тогда в руководстве было бы три главы: средняя называлась бы «оглавлением», а все мои главы были бы ее подразделами.   -  person jez    schedule 27.03.2020
comment
У вас может быть две разные индексные страницы: одна для HTML (index.rst) и одна для PDF (latexindex.rst). Мы делаем это в документации Pyramid. Подробнее о реализации см. в репозитории.   -  person Steve Piercy    schedule 27.03.2020
comment
Не уверен, что понимаю проблему. Могут потребоваться некоторые подробности, возможно, предоставьте минимальный воспроизводимый пример. В частности, я считаю, что было бы интересно посмотреть, какие стили заголовков вы используете, и соответствуют ли они друг другу.   -  person sinoroc    schedule 27.03.2020
comment
@sinoroc Приведенный выше список действительно был задуман как минимальный воспроизводимый пример, и я не могу представить, как сделать его еще более минимальным или более воспроизводимым, чем он уже есть, за исключением (см. редактирование), чтобы дать содержимое одного из файлов, на которые ссылаются в Ток. Как видите, я использую стиль заголовка, подчеркнутый символами = (так же, как заголовок Quickstart в index.rst, потому что я хочу, чтобы они были родственными Quickstart).   -  person jez    schedule 28.03.2020
comment
@StevePiercy Большое спасибо — для меня это ново и очень ценно знать, что вы можете переключаться на разные индексные файлы для разных типов сборки. Результат вы получите на docs.pylonsproject.org/_/downloads/ пирамида/en/latest/pdf не совсем то, что я ищу (все ваши главы выходят как разделы безымянной главы 0), но это, безусловно, дает мне представление о том, как можно взломать всю эту проблему.   -  person jez    schedule 28.03.2020
comment
@jez Мой плохой. Я был сбит с толку, потому что не видел связи между скриншотом и фрагментом кода. Но полезно посмотреть содержимое одного из других файлов. Я помню, что меня тоже не совсем устраивала вся эта тематика, когда я начинала работать с Sphinx, так что стоит того, вот как я это делаю сейчас, может быть, вы сможете что-то из этого взять : github.com/sinoroc/kb   -  person sinoroc    schedule 28.03.2020
comment
Я, вероятно, просто оставил бы оглавление отдельно в отдельном документе. Кажется, это решает большинство проблем с контуром документа для вывода Latex/PDF.   -  person sinoroc    schedule 28.03.2020

Ответы (2)


arrow_upward
1
arrow_downward

Как предложил jez, вы можете получить дочерние элементы в качестве глав, если включите их в качестве первого элемента в index.rst перед другими заголовками:

================
 Document title
================

.. toctree::
   :hidden:

   installation
   gettingstarted
   usage
   api_reference
   explanations



Hello
-----
special stuff that will show first in the html docs..

Second heading
--------------
mor text

Я установил его на :hidden:, чтобы просто применить это как структуру бокового меню и/или версии PDF. Затем вы можете использовать любую разметку для остальной части страницы, чтобы она хорошо выглядела в html-документах (например, трюки с двумя и тремя столбцами, которые я видел). Это пользовательское форматирование (Hello и и второй заголовок) станет дополнительной главой в конце документа.... не самое лучшее... но все же полезное: эй, кстати, как только вы прочитали всю эту книгу, вот были ссылки на лучшие части ;)

На самом деле, все это хаки, а реальные решения - это отдельный индекс для PDF, это лучший подход, как упомянул Стив, возможно, с некоторыми include, чтобы избежать дублирования.

person ivan    schedule 20.04.2020

arrow_upward
0
arrow_downward

Один из ответов или, скорее, обходной путь, по-видимому, заключается в том, чтобы вообще избегать использования каких-либо заголовков (кроме основного заголовка верхнего уровня «Бла») перед оглавлением. Затем записи toc включаются в качестве глав. «Быстрый старт» можно было превратить в отдельную главу, включенную в оглавление, в латексной версии. (Чтобы html-версия и латексная версия отличались друг от друга, как предлагает @StevePiercy в комментариях, настройте другой индексный файл для латексного режима в параметре latex_documents параметра conf.py.)

person jez    schedule 28.03.2020