Блог

Главная - Вопросы по программированию - Как сгенерировать табличный вывод в reStructuredText без использования формата ПЕРВОЙ таблицы?

Как сгенерировать табличный вывод в reStructuredText без использования формата ПЕРВОЙ таблицы?

#python-sphinx #tablelayout #restructuredtext #docutils

#python-sphinx #tablelayout #restructuredtext #документация #docutils

Вопрос:

Я пытаюсь перенести наши документы 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 table. Но я не могу найти хороших примеров пользовательских директив для обработки этого так, как я хочу, что было бы что-то вроде

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

Как я могу выполнить это в reStructuredText?

Ответ №1:

Я не думаю, что вам нужна пользовательская директива. Вы пробовали использовать стандартную таблицу списка reStructuredText?

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

 .. 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% пути.

Комментарии:

1. Мне нравится этот. Я согласен, что это всего лишь 90% — я бы предпочел, чтобы поля были более явно «полями», а не просто позиционными — но это достаточно просто и понятно, что, вероятно, лучше, чем сложность пользовательской директивы. Спасибо!

2. Есть ли способ, которым это может быть автоматически сгенерировано с помощью каких-либо плагинов? Например, у меня есть несколько таблиц, которые нужно создать с разными строками и столбцами. Я ищу способ сгенерировать их быстрее.