Sphinx: The caption of a toctree is not translated into latex "parts"

[Paebbels]

My documentation is on a good way (maybe you noticed a bunch of issue reports written while using Sphinx for a big project :) ), so I checked the LaTeX backend.

The online documentation at ReadTheDocs has "parts", created by by multiple toctree directives, each with its own caption. I would expect (with latex_use_parts = True) that caption gets translated to a \part{...} in LaTeX.

ReadTheDocs HTML Output:

The generated PDF file looks like this (Table of Contents):

The red drawing shows the generated parts instead of chapters. And blue shows the intended parts - matching the HTML version's navigation bar.

---

This is my (shortened) master document's toctree content:

.. toctree::
   :caption: Introduction
   :hidden:

   WhatIsPoC/index
   References/Licenses/License

.. toctree::
   :caption: Main Documentation
   :hidden:

   UsingPoC/index
   ConstraintFiles/index

.. toctree::
   :caption: Appendix
   :hidden:

   ChangeLog/index
   genindex

---

I also tried to workaround this issue with 2 approaches.

1. Different toctree per backend switch by .. only:: html/latex

   The PoC-Library Documentation
   #############################
   
   PoC - "Pile of Cores" provides implementations for often required hardware
   
   .. only:: html
   
     This document was generated on |docdate|.
   
     .. toctree::
        :caption: Introduction
        :hidden:
   
        WhatIsPoC/index
        References/Licenses/License
   
     .. toctree::
        :caption: Main Documentation
        :hidden:
   
        UsingPoC/index
        ConstraintFiles/index
   
   .. only:: latex
   
     Introduction
     """"""""""""
   
     .. toctree::
        :hidden:
   
        WhatIsPoC/index
        References/Licenses/License
   
     Main Documentation
     """"""""""""""""""
   
     .. toctree::
        :hidden:
   
        UsingPoC/index
        ConstraintFiles/index
   

2. Intermediate headlines enabled by .. only:: latex:

   The PoC-Library Documentation
   #############################
   
   PoC - "Pile of Cores" provides implementations for often required hardware
   
   .. only:: latex
   
     Introduction
     """"""""""""
   
   .. toctree::
     :hidden:
   
     WhatIsPoC/index
     References/Licenses/License
   
   .. only:: latex
   
     Main Documentation
     """"""""""""""""""
   
   .. toctree::
     :hidden:
   
     UsingPoC/index
     ConstraintFiles/index
   

[jfbu]

Here is a way, perhaps there is a better Sphinxesque method.

master index.rst file:

.. raw:: latex

   \part{Introduction}

.. toctree::
   :caption: Introduction
   :hidden:

   WhatIsPoC/index
   References/Licenses/License

.. raw:: latex

   \part{Main Documentation}

.. toctree::
   :caption: Main Documentation
   :hidden:

   UsingPoC/index
   ConstraintFiles/index

.. raw:: latex

   \part{Appendix}

.. toctree::
   :caption: Appendix
   :hidden:

   ChangeLog/index

produces:

edit: the image below shows that the first section What is PoC? did not make it to document, but this is fixed by adding a sectioning like

=============
MAIN DOCUMENT
=============

to the master toctree content file above.

There is slight problem that the top of TOC says "Introduction". Thus add this to conf.py:

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    'preamble': '\\addto\\captionsenglish{\\renewcommand{\\contentsname}{Table of contents}}',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

Don't use latex_use_parts or latex_toplevel_sectioning. The above tested with manual docclass. I don't know however how it will render on ReadTheDocs.

[Paebbels]

Hello, that seems to work on my local machine too.
I'll test this workaround on RTFD.

[tk0miya]

The :caption: option of toctree directive means a caption of table of contents. So LaTeX writer only uses it for the caption of ToC.
(In LaTeX writer, all toctree are combined to single toctree. so the first :caption: is used for the caption of ToC)

It does not mean document structure. so it is not used for "part". So please avoid it with adhoc way like raw and only directive.