find_tables(): opt-in layout union, grid refinement, merged-cell/header model, and Table.to_html()

docs/page.rst

@@ -452,7 +452,7 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       :arg bool final_filter: If `True` (default), the method will to remove rectangles having width or height smaller than the respective tolerance value. If `False` no such filtering is done.
 
-   .. method:: find_tables(clip=None, strategy=None, vertical_strategy=None, horizontal_strategy=None, vertical_lines=None, horizontal_lines=None, snap_tolerance=None, snap_x_tolerance=None, snap_y_tolerance=None, join_tolerance=None, join_x_tolerance=None, join_y_tolerance=None, edge_min_length=3, min_words_vertical=3, min_words_horizontal=1, intersection_tolerance=None, intersection_x_tolerance=None, intersection_y_tolerance=None, text_tolerance=None, text_x_tolerance=None, text_y_tolerance=None, add_lines=None, add_boxes=None, paths=None)
+   .. method:: find_tables(clip=None, strategy=None, vertical_strategy=None, horizontal_strategy=None, vertical_lines=None, horizontal_lines=None, snap_tolerance=None, snap_x_tolerance=None, snap_y_tolerance=None, join_tolerance=None, join_x_tolerance=None, join_y_tolerance=None, edge_min_length=3, min_words_vertical=3, min_words_horizontal=1, intersection_tolerance=None, intersection_x_tolerance=None, intersection_y_tolerance=None, text_tolerance=None, text_x_tolerance=None, text_y_tolerance=None, add_lines=None, add_boxes=None, paths=None, use_layout=True)
 
       Find tables on the page and return an object with related information. Typically, the default values of the many parameters will be sufficient. Adjustments should ever only be needed in corner case situations.
 
@@ -492,6 +492,8 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       :arg list paths: list of vector graphics in the format as returned be :meth:`Page.get_drawings`. Using this parameter will prevent the method to extract vector graphics itself. This is useful if the vector graphics are already available. This can save execution time significantly.
 
+      :arg bool use_layout: use layout analysis to gate line-based table candidates. Set to `False` for pure line-based detection.
+
       .. image:: images/img-findtables.*
 
       :returns: a `TableFinder` object that has the following significant attributes:

setup.py

@@ -623,6 +623,10 @@ def build():
     ret.append( (f'{g_root}/src/__main__.py', to_dir) )
     ret.append( (f'{g_root}/src/pymupdf.py', to_dir) )
     ret.append( (f'{g_root}/src/table.py', to_dir) )
+    ret.append( (f'{g_root}/src/_table_refine.py', to_dir) )
+    ret.append( (f'{g_root}/src/_table_spans.py', to_dir) )
+    ret.append( (f'{g_root}/src/_table_union.py', to_dir) )
+    ret.append( (f'{g_root}/src/_table_headers.py', to_dir) )
     ret.append( (f'{g_root}/src/utils.py', to_dir) )
     ret.append( (f'{g_root}/src/_wxcolors.py', to_dir) )
     ret.append( (f'{g_root}/src/_apply_pages.py', to_dir) )