Force Sphinx to use longtable directive, to correctly add page breaks in long tables

Question

I am working on a project where we generate documentation to HTML and PDF.

When tables have more than 30 lines, sphinx correctly uses the Latex longtable package. However, for smaller tables, it uses the tabulary package instead.

My problem is that I have some tables with less than 30 rows, but since the rows are large, I require a page break.

From all of my reading (specifically, here: https://github.com/sphinx-doc/sphinx/issues/1898), it seems I should simply force sphinx to use longtable by specifying ":class: longtable"

Unfortunately, I have not been successful in adding this specification, because my tables are not specified using a separate directive.

Here's how my tables are defined:

.. tabularcolumns:: |p{1cm}|p{4cm}|p{10cm}|

+--------+-----------------+--------------------------+
| Step # | Process Step(s) | Detail                   |
+========+=================+==========================+
| 1      | Testing         | Testing  Testing Testing |
+--------+-----------------+--------------------------+

All the online examples I'm getting use list-tables or csv-tables and then add the longtable command as part of the relevant directive. For example:

.. tabularcolumns:: |p{1cm}|p{7cm}|

.. csv-table:: Lorem Ipsum
   :file: _files/lorem-tab.csv
   :header-rows: 1
   :class: longtable

I've tried this, but unfortunately it did not work:

.. tabularcolumns:: |p{1cm}|p{4cm}|p{10cm}|
   :class: longtable

+--------+-----------------+--------------------------+
| Step # | Process Step(s) | Detail                   |
+========+=================+==========================+
| 1      | Testing         | Testing  Testing Testing |
+--------+-----------------+--------------------------+

It gives the following exception when trying to make the pdf:

! Package array Error:  Illegal pream-token (:): `c' used.

See the array package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              

l.663 :class: longtable}

Answer 1

Following some Rubber-duck debugging with a colleague, we determined that I needed to add the ..table directive. This then wraps my simple table and provides a spot for the :class: definition.

So my table is now defined as follows:

.. tabularcolumns:: |p{1cm}|p{4cm}|p{10cm}|

.. table:: My Table
   :widths: auto
   :class: longtable

   +--------+-----------------+--------------------------+
   | Step # | Process Step(s) | Detail                   |
   +========+=================+==========================+
   | 1      | Testing         | Testing  Testing Testing |
   +--------+-----------------+--------------------------+

This sorts our the issue, and it still reads the column spec from the tabularcolumns directive.