Как сгенерировать табличный вывод в reStructuredText без использования формата таблицы RST?

Я пытаюсь перенести наши документы API и схему генератора проприетарной документации в reStructuredText. Сложнее всего то, что у нас есть табличное представление деталей API, закодированное непосредственно в HTML, а-ля:

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

(т.е. в настоящее время это кодируется как <tr><td class='param'>id</td><td class='required'>Yes</td>...)

Я хочу сделать это в RST, но сделать это семантически, а не просто использовать формат таблицы RST. Но я не могу найти хороших примеров пользовательских директив для обработки так, как я хочу, что-то вроде

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

Как я могу сделать это в reStructuredText?


python-sphinx restructuredtext tablelayout docutils
person mrisher    schedule 19.10.2011    source источник

Ответы (1)


arrow_upward
4
arrow_downward

Я не думаю, что вам нужна пользовательская директива. Пробовали ли вы использовать стандартный реструктурированный текст List Table ?

Это выглядит примерно так (со связанной страницы):

.. 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!

Заголовки таблиц находятся в первом элементе внешнего списка (по крайней мере, в этом примере). Даже если это не совсем то, что вы хотите, я думаю, что это поможет вам достичь цели как минимум на 90%.

person Kevin Horn    schedule 09.12.2011
comment
Мне нравится этот. Я согласен, что это только на 90% - я бы предпочел, чтобы поля были более явными полями, а не просто позиционными, - но это просто и достаточно чисто, что, вероятно, лучше, чем сложность пользовательской директивы. Спасибо! - person mrisher; 11.12.2011