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.