Close sphinx-doc#6837: LaTeX: Support a nested table

CHANGES

@@ -21,6 +21,7 @@ Features added
 * #6910: inheritance_diagram: Make the background of diagrams transparent
 * #6446: duration: Add ``sphinx.ext.durations`` to inspect which documents slow
   down the build
+* #6837: LaTeX: Support a nested table
 
 Bugs fixed
 ----------

sphinx/writers/latex.py

@@ -646,7 +646,7 @@ def __init__(self, document: nodes.document, builder: "LaTeXBuilder") -> None:
                                                        latex_engine=self.config.latex_engine)
         self.context = []                   # type: List[Any]
         self.descstack = []                 # type: List[str]
-        self.table = None                   # type: Table
+        self.tables = []                    # type: List[Table]
         self.next_table_colspec = None      # type: str
         self.bodystack = []                 # type: List[List[str]]
         self.footnote_restricted = None     # type: nodes.Element
@@ -783,6 +783,14 @@ def render(self, template_name: str, variables: Dict) -> str:
 
         return renderer.render(template_name, variables)
 
+    @property
+    def table(self) -> Table:
+        """Get current table."""
+        if self.tables:
+            return self.tables[-1]
+        else:
+            return None
+
     def visit_document(self, node: Element) -> None:
         self.curfilestack.append(node.get('docname', ''))
         if self.first_document == 1:
@@ -1079,11 +1087,21 @@ def visit_tabular_col_spec(self, node: Element) -> None:
         raise nodes.SkipNode
 
     def visit_table(self, node: Element) -> None:
-        if self.table:
+        if len(self.tables) == 1:
+            if self.table.get_table_type() == 'longtable':
+                raise UnsupportedError(
+                    '%s:%s: longtable does not support nesting a table.' %
+                    (self.curfilestack[-1], node.line or ''))
+            else:
+                # change type of parent table to tabular
+                # see https://groups.google.com/d/msg/sphinx-users/7m3NeOBixeo/9LKP2B4WBQAJ
+                self.table.has_problematic = True
+        elif len(self.tables) > 2:
             raise UnsupportedError(
-                '%s:%s: nested tables are not yet implemented.' %
+                '%s:%s: deeply nested tables are not implemented.' %
                 (self.curfilestack[-1], node.line or ''))
-        self.table = Table(node)
+
+        self.tables.append(Table(node))
         if self.next_table_colspec:
             self.table.colspec = '{%s}\n' % self.next_table_colspec
             if 'colwidths-given' in node.get('classes', []):
@@ -1100,7 +1118,7 @@ def depart_table(self, node: Element) -> None:
         self.body.append(table)
         self.body.append("\n")
 
-        self.table = None
+        self.tables.pop()
 
     def visit_colspec(self, node: Element) -> None:
         self.table.colcount += 1

tests/roots/test-nested-tables/index.rst

@@ -0,0 +1,16 @@
+nested-tables
+=============
+
+.. list-table::
+   :header-rows: 1
+
+   * - heading
+     - heading
+   * - content
+     - .. list-table::
+          :header-rows: 1
+
+          * - heading
+            - heading
+          * - content
+            - content

tests/test_build_latex.py

@@ -1470,3 +1470,9 @@ def test_latex_elements_extrapackages(app, status, warning):
     app.builder.build_all()
     result = (app.outdir / 'test.tex').text()
     assert r'\usepackage{foo}' in result
+
+
+@pytest.mark.sphinx('latex', testroot='nested-tables')
+def test_latex_nested_tables(app, status, warning):
+    app.builder.build_all()
+    assert '' == warning.getvalue()