How to create a PDF in reStructuredText?

Question

The documentation for the uncertainties Python package is written in reStructuredText, for the Sphinx documentation system. The HTML looks fine. I would like to create a PDF version. The goal is to have a "chapter" for each of the web page.

However, what happens is that the PDF generated by the ReST files transforms the (HTML) sections of index.html into individual chapters (which I don't want: the PDF should have them as sections too). Another problem is that all HTML pages after the main page appear in the PDF as subsections of the section where the toctree directive appears (i.e., in the Acknowledgment section of the main page).

So, how should the ReST file be structured so that (1) the web documents look the same as they are now, and (2) each web page corresponds to a PDF chapter. Any help would be much appreciated!

Answer 1

There is a solution. If I remember correctly, the key points were:

• Use a special Table of Contents as the master document (I used index_TOC.rst instead of the default index.rst): in conf.py
  • master_doc = 'index_TOC'
  • latex_documents = [('index_TOC', 'uncertaintiesPythonpackage.tex',…]

• The new Table of Contents file index_TOC.rst contains a ToC like

  TOC
  ===
  
  .. toctree::
     :hidden:
     :maxdepth: 1
  
     index
     user_guide
     numpy_guide
     tech_guide
  

Thus, the web version still opens onto the main index.rst text, and the PDF (LaTeX) version has each ReST file in a separate chapter.