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?

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.