LaTeX: Bug if a table is inside a multi-row/column cell of another table

[fournier-p]

Describe the bug

As indicated in the title, if a table is defined in a multi-row or multi-column (or both) cell of another table, then the produce latex file will not be valid.

How to Reproduce

This minimal rst is enough to trigger the problem:
(The + at the middle of the first line is intended to trigger a multi-column cell)

+---+---+
| +---+ |
| |   | |
| +---+ |
+-------+

Environment Information

Platform:              linux; (Linux-5.10.0-18-amd64-x86_64-with-glibc2.31)
Python version:        3.12.8 (main, Apr 10 2025, 17:00:17) [GCC 10.2.1 20210110])
Python implementation: CPython
Sphinx version:        8.2.3
Docutils version:      0.20.1
Jinja2 version:        3.1.2
Pygments version:      2.19.1

Sphinx extensions

No extension needed.

Additional context

I could dig a bit more into the issue and from what I found it seems that the needs_linetrimming value of the LatexTranslator class is not properly used.

With the example I gave above, we enter visit_entry and depart_entry both twice:

• First we go into visit_entry for the outer table, in which we set self.needs_linetrimming to 1
  • Then we go into visit_entry a second time, this time for the inner table. In this case we wouldn't be setting self.needs_linetrimming to 1 but in any case it is already set.
  • Then we go into depart_entry for the inner table, and since self.needs_linetrimming == 1 we then call popbody even though it was needed for the entry of the outer table.
• Finally, we go into depart_entry a second time, for the outer table, in which we will not call popbody because self.needs_linetrimming was set to 0 in the previous call of depart_entry

One way to fix this would be to use node attributes to set it on the entry node which actually needs line trimming.

[jfbu]

Thanks for report. Other "nested tables" issues include #11498 and #11515. The latex table rendering code is complex particularly for rendering merged cells especially when they involve both multiple rows and multiple columns.

[jfbu]

Thanks for the analysis. The produced LaTeX is completely mangled due to the reasons you mention. I observed this is "fixed" partially if I make the needs_linetrimming a flag of the table rather than a flag of the LaTeXTranslator. Miraculously, the PDF compiles then, and all our existing table tests pass. The nested table is not occupying two columns though.

Edit: actually it does, but is aligned left, so in my test with minimal content I thought it would not.

General remark: both the Python code and the LaTeX macro layer have reached a level of complexity which renders maintenance very hard. Unfortunately LaTeX does not provide native satisfactory solutions to challenges of merged cells possibly containing code-blokcs or lists.

[jfbu]

Please try out our new HEAD. Perhaps your real life project will compile to PDF. Caveat: our multicolumn code always uses "l" i.e. left-alignment. So only if the included table in the cell is wide-enough will it look about right. There may be some sub-optimal things about rowcolors which I have not investigated and may deserve another ticket.

hint you may get better result using latex_use_latex_multicolumn = True in your conf.py. It will not be compatible with certain inputs, though, but gives currently better result on your minimal example.