CODEWITHSUNDEEP
latexpython-sphinxrestructuredtext
Kedar
Kedar

Reputation: 13

Headings in index.rst do not appear in LaTeX build

I am trying to build a PDF from RST docs. The index.rst doc is not empty in this case:

############
How to Build
############

The build blah blah balh 

.. toctree::
   :hidden:

   file1
   file2
   file3

In the PDF output, the text "The build blah blah balh" appears without any heading at all! The HTML output is OK (the heading "How to Build" appears correctly), which is why I categorized it as a LaTeX issue, not a Sphinx one.

Is there any way I can get this heading to appear in the PDF?

Note:

The docs came from some other team, so I cannot edit them beyond a certain point. For example, I cannot move all the content from index.rst into another new file (which would have been really convenient).

Upvotes: 1

Views: 511

Answers (1)

john-hen
john-hen

Reputation: 4866

Documents produced by the LaTeX builder usually start with a title page, containing the document title, author, and date of publication, followed by the table of contents, followed by the individual chapters/sections listed in that table of contents. So what you're trying to accomplish here is adding some front matter with a heading that doesn't show up in the table of contents. Which is a bit unusual.

We can tell Sphinx to use the top-level heading from the root document (index.rst) as the LaTeX document title in conf.py:

latex_documents = [
    ('index', 'output.tex', '', 'Author Name', 'manual', False)
]

With the example from the question, the empty string in third position will be replaced with "How to Build" and appear on the title page. This is consistent with the HTML output, where it is the title of the start page.

However, the document title is not a section heading and the following paragraph then appears without one. The solution is to add an extra section heading, but only in the LaTeX document, not in the HTML build.

############
How to Build
############

.. raw:: latex

    \section*{How to Build}

This uses the raw directive to insert an unnumbered section heading in the LaTeX document only.

Upvotes: 0

Related Questions