How to generate tabular output in reStructuredText without using RST table format?

Question

I'm trying to migrate our API docs and their proprietary documentation generator schema to reStructuredText. The piece that gives the hardest time is, we have a tabular representation of API details, coded directly in HTML, a la:

--------+------------+--------+--------------------------------+
Param   |  Required  |  Type  |  Description
----------------------------------------------------------------
id      |     Yes    | int    | This is the ID of the record...
content |     No     | string | Optional string contents...

(i.e. this is currently coded as <tr><td class='param'>id</td><td class='required'>Yes</td>...)

I want to do this in RST but do it semantically, rather than just using an RST table format. But I can't find any good examples of custom directives to handle this the way I want, which would be something like

:.. parameter-table:: My Parameter Table
    .. item::
       :param: "id"
       :required: true
       :type: "int"
       :desc: "This is the ID of the record..."

How can I accomplish this in reStructuredText?

Filiform

Answer 1

I don't think you need a custom directive. Have you tried using a standard restructuredText List Table?

It looks something like this (from the linked page):

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

The table headers are in the first outer list item (in this example, at least). Even if this isn't exactly what you want I think this will get you at least 90% of the way there.

Disrelish

I like this one. I agree it's only 90% -- I would prefer if the fields were more explicitly "fields" instead of just positional -- but it is simple and clean enough that it's probably better than the complexity of a custom directive. Thanks! – Filiform

Is there a way this can be auto-generated using any plugins? Like I have multiple tables to be created with different rows and columns. I am looking a way to generate these faster. – Wun