Sphinx: Sub TOC is not shown in PDF output.

[Zimmi48]

Describe the bug

There is a behavior discrepancy between the HTML and PDF outputs when using a sub TOC, i.e. when using a .. toc:: somewhere else than on the index page.

To Reproduce
Steps to reproduce the behavior:

mkdir /tmp/sphinx-repro
cd /tmp/sphinx-repro
sphinx-quickstart --quiet --author x --project y
for i in A B{1,2}; do printf "$i\n==\n\nContent of $i." > "$i.rst"; done
cat > index.rst <<< '.. toctree::

   A
   B
'
cat > B.rst <<< 'B
==

This is the table of content for this chapter:

.. toctree::

   B1
   B2

Additional explanations on this chapter.
'
make html
make latexpdf

Expected behavior
I would like to see in both outputs a sub TOC at the beginning of chapter B. It is only shown in the HTML output. In the PDF output, it is directly replaced by the content of the included files.

In practice, in this repro case, chapter A doesn't even exist in the PDF output, but this is another, unrelated bug.

Screenshots

HTML:

PDF:

Environment info

• OS: Linux
• Python version: 3.7.6
• Sphinx version: 2.3.1
• Sphinx extensions: none

[tk0miya]

I think this is the intended behavior. The builders that output multiple files (ex. HTML) treat a toctree definition as a collection of hyperlinks. On the other hand, the builders that output a single file (ex. LaTeX, man page, Single HTML) are replace a toctree definition with the content of documents on the toctree.

[cpitclaudel]

That's fair, but on the other hand it makes it hard to consistent results between two output formats. Is there currently a recommended way to get similar output (list of headers, followed by some text) in both HTML and PDF?

[jfbu]

@cpitclaudel Here is workaround, at LaTeX level. It is not a Sphinx solution.

B
==

This is the table of content for this chapter:

.. raw:: latex

   \etocsettocstyle{}{}\localtableofcontents

.. toctree::

   B1
   B2

Additional explanations on this chapter.

and

latex_elements = {
    'preamble': r'\usepackage{etoc}',
}

in conf.py.

[cpitclaudel]

I think this almost works, but the additional explanations on this chapter will still end up after the contents, right?

[jfbu]

I think this almost works, but the additional explanations on this chapter will still end up after the contents, right?

Yes you are right. You could fix that with some duplication using .. only:: latex and .. only:: not latex I guess... a bit painful. will try to think of some other approach.

[jfbu]

only to say

B
==

This is the table of content for this chapter:

.. raw:: latex

   \etocsettocstyle{}{}\localtableofcontents

.. only:: latex

   Additional explanations on this chapter.

.. toctree::

   B1
   B2

.. only:: not latex

   Additional explanations on this chapter.

is what I had in mind and I don't have any other idea at this stage.

[Zimmi48]

I think this is the intended behavior. The builders that output multiple files (ex. HTML) treat a toctree definition as a collection of hyperlinks. On the other hand, the builders that output a single file (ex. LaTeX, man page, Single HTML) are replace a toctree definition with the content of documents on the toctree.

I am not a big Sphinx expert but I feel like this is not sufficiently documented (i.e. this idea does not appear at all on this page https://www.sphinx-doc.org/en/1.5/markup/toctree.html).

[tk0miya]

I just added an explanation in #7348.

Thanks,

[jfbu]

@Zimmi48 There is an alternative to get same HTML and LaTeX looks from same source. You could do this

B
==

This is the table of content for this chapter:

.. contents::
   :local:

Additional explanations on this chapter.

.. include:: B1.rst

.. include:: B2.rst

but then B1.rst and B2.rst titles must be at next sublevel, i.e. not use

B1
==

Content of B1.

but

B1
--

Content of B1.

However, the B1 and B2 contents will then be embedded in B page in HTML output.

But in a way, this makes HTML and LaTeX produce comparable outputs: one LaTeX chapter corresponds to one HTML page and both have table of ocntents at start and possibly a description after it.

[Zimmi48]

Thanks, but the fact that this is split on several pages in the HTML output was something that we wanted to have. Your previous solution is a good enough workaround fortunately!

[jfbu]

Your previous solution is a good enough workaround fortunately!

glad it worked :)