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).

Answer 1

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.)

Answer 2

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.