python-sphinx - 如何在不使用 RST 表格格式的情况下在 reStructuredText 中生成表格输出？

Question

我正在尝试将我们的 API 文档及其专有文档生成器模式迁移到 reStructuredText。最困难的部分是，我们有一个 API 细节的表格表示，直接用 HTML 编码，a la:

--------+------------+--------+--------------------------------+
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 表格式。但我找不到任何关于 custom directives 的好例子以我想要的方式处理这个问题，就像

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

如何在 reStructuredText 中完成此操作？

Answer 1

我认为您不需要自定义指令。您是否尝试过使用标准的重组文本 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% 的工作。