Sphinx: The LaTeX builder doesn't handle multiple toctrees with captions well

[cpitclaudel]

Problem

The HTML builder has good support for multiple separate toctrees with captions, like this:

.. toctree::
   :caption: AAA

   A1
   A2

.. toctree::
   :caption: BBB

   B1
   B2

In Alabaster it's rendered like this:

  A1
  A2

BBB

  B1
  B2

And in the RTD theme A1 and A2 are grouped in the table of contents:

The LaTeX builder, on the other hand, gets confused when presented with the same input:

Procedure to reproduce the problem

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==" > "$i.rst"; done
cat > index.rst <<< '.. toctree::
   :caption: AAA

   A1
   A2

.. toctree::
   :caption: BBB

   B1
   B2
'
make latexpdf

Expected results

The table of contents should be split into two parts in LaTeX like in HTML

Environment info

• OS: GNU/Linux
• Python version: 3.5.2
• Sphinx version: 1.7.1

[jfbu]

I think LaTeX should use \part for that (for toplevel toctree). I.E. LaTeX should look something like

\begin{document}

\maketitle
\sphinxtableofcontents
\phantomsection\label{\detokenize{index::doc}}

\part{AAA}
\label{detokenize{index::toctree_aaa}}

\chapter{A1}
\label{\detokenize{index::toctree_aaa::a1}}

\chapter{A2}
\label{\detokenize{index::toctree_aaa::a2}}

\part{BBB}
\label{detokenize{index::toctree_bbb}}

\chapter{B1}
\label{\detokenize{index::toctree_bbb::b1}}

\chapter{B2}
\label{\detokenize{index::toctree_bbb::b2}}


\renewcommand{\indexname}{Index}
\printindex
\end{document}

but also the Table of Contents Heading should not be AAA. Here is with such manual modifications:

[tk0miya]

I added the :caption: option for toctree to show a caption in content. But I did not intend to show it in ToC. So I feel the captions should not appear in sidebar.

Anyway, as discussed in #4733 (and other issues labeled as toctree), "Part like" ToC mechanism is needed by some users.

[jmlarson1]

Was there a resolution to this issue?

[ScriptAutomate]

I added the :caption: option for toctree to show a caption in content. But I did not intend to show it in ToC. So I feel the captions should not appear in sidebar.

Anyway, as discussed in #4733 (and other issues labeled as toctree), "Part like" ToC mechanism is needed by some users.

@tk0miya : could you provide some clarification on this? I've been using some themes that make use of the :caption: directive as a way of creating section headers in TOC in the resulting HTML. Though, as experienced by @cpitclaudel, two problems occur:

• The resulting PDF TOC seems to ignore :caption: content for multiple toctrees.
• The very first :caption: ends up becoming the TOC header in a resulting PDF, while ignoring the rest of the :caption: values in the toctrees.

_Note: Another open issue seems to be attempting a similar goal in #3357_

Is there current guidance in how users can accomplish this goal at the moment:

.. toctree::
   :caption: AAA

   A1
   A2

.. toctree::
   :caption: BBB

   B1
   B2

In order to achieve both captioned sections with make html and TOC captioned sections with pdf gen?

I'm using:

• Sphinx 3.0.3
• Python 3.8.2
• OS: GNU/Linux

[tk0miya]

At present, no way to do that. I'll work on it nearly future (after the refinement of autodoc and autosummary...)