Python Sphinx skips first section when generating pdf

Question

I use sphynx to generate documentation from static .rst files (no docstrings extraction).

I have two files in my repository:

index.rst

.. toctree::

   intro

and intro.rst

Will be skipped
===============

Where is my parent section?
---------------------------

Second section
==============

Below is screenshot of pdf obtained by running sphinx-build -b latex . _build; cd _build; pdflatex * :

Flabbergasting or what?

Answer 1

Thanks for providing the working example. I can reproduce your observation with Sphinx 1.2.3 on Windows. As far as I can see, the HTML output is working as expected. With the LaTeX builder, the following document structure is produced:

\chapter{Where is my parent section?}
\label{intro:will-be-skipped}\label{intro::doc}\label{intro:where-is-my-parent-section}

\chapter{Second section}
\label{intro:second-section}

I found suspicious about your document that it did not define a title. As a workaround I have found that adding a higher hierarchy works, whereas it does not matter if you put it into index.rst or intro.rest. This is the modified index.rst:

=====
TITLE
=====

.. toctree::

   intro

Resulting in:

I have then further looked out for this problem, and found this Bitbucket/GitHub issue dealing with the very same issue (it is from 2011):

https://bitbucket.org/birkenfeld/sphinx/issue/632/section-versus-chapter-oddity-in-latex https://github.com/sphinx-doc/sphinx/issues/632

Quote:

Your index.rst doesn't have a title, right? Basically Sphinx gobbles up the most toplevel title (which is then replaced by the document frontmatter).

That issue was put "on hold" back in 2011, probably it was not considered failing behavior. It was then just recently closed on GitHub without being "fixed". So, as Georg wrote in that ticket, Sphinx indeed just consumes the highest hierarchy whereas its content does not appear anywhere.

Therefore: adding a "title hierarchy", no matter how you name it, is the proper solution.

Answer 2

Using Ubuntu 14.04 and texlive if I create a new Sphinx project with sphinx-quickstart (separate source and build directories), drop the example files into the source directory and build with:

$ make latexpdf

I see the see the Will be skipped heading in the PDF output.

The OPs original command was

$ sphinx-build -b latex . _build; cd _build; pdflatex *

to build the documentation, which is slightly different than the latexpdf target in the Makefile which uses latex all-pdf. However, if I create a new project directory with the same conf.py that sphinx-quickstart created I still see the Will be skipped output in the PDF using the OPs command sequence. I would look into the conf.py settings that you are using, those might give a clue to the solution.