How can I force sphinx to end a chapter when making a pdf?

Question

I'm using sphinx, hosted on https://readthedocs.org , to generate documentation in both HTML and PDF formats. The HTML works fine. The PDF also builds successfully, but has a problem with nesting: I would like each of the top-level .rst documents, linked from my table-of-contents, to be included in the PDF as top-level "chapters". However, they are in fact included as subsections, subordinate to the front-page index.rst content. Here's what I have in my 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`

...and this screenshot shows what I get in the PDF:

...whereas I would like "How to Install Blah" to be chapter 2, "Basic Usage" to be chapter 3, and so on. (The HTML looks perfectly organized: the landing page is divided under three section headings called Quickstart, then Table of Contents, then Indices and Tables.)

My search-foo has failed me in finding any way of telling sphinx, in the context of making PDFs, "go up two levels here" or "end the current chapter here" (see the comment "NEED SOME DIRECTIVE HERE" in the index.rst listing above). Is this in fact possible?

The content of one of the chapter files, Installation.rst, is as follows:

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

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

The other files, BasicUsage.rst, AdvancedUsage.rst and License.rst can either be removed from the toc for the purposes of the example, or constructed the same way: a one-liner with an =-underlined heading (same level of underlining as "Quickstart", above).

You could insert a new section heading `Table of Contents` with `===` underscores just above your `toctree`. — Steve Piercy, Mar 27 '20 at 03:43
That would improve things but only slightly. Then there would be three chapters in the manual: the middle one would be called “table of contents” and all my chapters would be subsections of it — jez, Mar 27 '20 at 11:17
You could have two different index pages, one for HTML (index.rst) and one for PDF (latexindex.rst). We do that in Pyramid's docs. Check out the [repo](https://github.com/Pylons/pyramid/tree/master/docs) for implementation details. — Steve Piercy, Mar 27 '20 at 12:41
Not sure I understand the issue. Some details might be needed, maybe provide a [mcve]. In particular, I believe it would be interesting to see what heading styles you are using, and if they are consistent. — sinoroc, Mar 27 '20 at 19:14
@sinoroc The listing above was indeed intended to be minimal reproducible example and I can't imagine how to make it any more minimal or more reproducible than it already is—except (see edit) to give the content of one of the files referred to in the toc. As you can see, I use the heading style underlined with `=` characters (same as the heading "Quickstart" in `index.rst`, because I want them to be siblings of "Quickstart"). — jez, Mar 27 '20 at 21:31
@StevePiercy Many thanks—it's new to me, and very valuable, to know that you can divert to different index files for different build types. The result you get in https://docs.pylonsproject.org/_/downloads/pyramid/en/latest/pdf/ is not quite what I'm looking for (your chapters all come out as sections of the unnamed Chapter 0) but this certainly gives me a lead towards ways this whole issue might be hacked. — jez, Mar 27 '20 at 22:07
@jez My bad. I was confused because I couldn't see the relation between the screenshot and the code snippet. But seeing the content of one of the other files is helpful. I remember that I also wasn't entirely satisfied with this whole thematic when I started working with _Sphinx_, so for what it's worth, this is how I do it now, maybe you can take something out of it: https://github.com/sinoroc/kb — sinoroc, Mar 28 '20 at 16:21
I probably would just leave the table of contents on its own in its own document. It seems to solve most of the document outline issues for the Latex/PDF output. — sinoroc, Mar 28 '20 at 17:39

score 2 · Answer 1 · answered Apr 20 '20 at 22:29

As suggested by jez, you can get toc children as chapters if you include it as the first thing in the index.rst, before other headings:

================
 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

I set it to :hidden: to just enforce this as the structure of the side menu and/or the PDF version. You can then use whatever markup you want for the rest of the page so that it will appear nice on the html docs (e.g. the two- and three-column tricks I've seen). This custom formatting (Hello and and Second heading) will end up as an extra chapter in the end of the document.... not the best... but still usable: hey BTW, once you've read this whole book, here were the links to the best parts ;)

Really though, all of these are hacks and the real solutions is separate index for the PDF are the better approach as mentioned by Steve, possibly with some includes to avoid duplication.

score 0 · Answer 2 · answered Mar 28 '20 at 19:13

One answer, or rather workaround, seems to be to avoid using any headings at all (except for the top-level main heading "Blah") before the table of contents. Then the toc entries get included as chapters. "Quickstart" could be turned into its own chapter, included in the toc, in the latex version. (To make the html version and the latex version diverge from each other, as suggested by @StevePiercy in the comments, configure a different index file for latex mode in the latex_documents parameter of conf.py.)

How can I force sphinx to end a chapter when making a pdf?

2 Answers2