我可以在一行中记录多个常量吗？

Question

我正在记录一个模块，它公开一组不透明的常量标记值，代表状态机的不同可能状态。

孤立地谈论他们每个人真的没有什么有趣的。目前我的文档看起来像：

[... state machine diagram ...] [... high level explanation ...]
States are represented using one of the following constants:

.. data:: IDLE
.. data:: SEND_RESPONSE
.. data:: SEND_BODY
[and so on for another 10 lines]

为每个常量创建一个 .. data:: 条目的好处是，这意味着以后我可以通过编写类似

的超链接回到这些文档

If the connection is in the :data:`IDLE` state...

它们出现在索引中，等等。糟糕的是，这些常量中的每一个都有一个大的粗体段落，所以整个列表最终就像一整屏呈现的文档，基本上没有内容。

我想以某种方式将它们列在一行中 ("One of the following constants: IDLE, SEND_RESPONSE, ...")，或者甚至完全不列出这些列表 ("For each of the states named in the above diagram, there is a corresponding module-level constant ...")，但仍具有 sphinx 的索引和交叉链接仍然有效。

也许有什么方法可以告诉 sphinx "hey psst, you don't need to render anything here but just FYI this paragraph documents the following data items"？或者关于如何减少这里的混乱的任何其他想法？

Answer 1

想通了！你可以这样写：

.. data:: IDLE
          SEND_RESPONSE
          SEND_BODY
          ...

并且至少在 readthedocs 主题中它将呈现如下：

我可以在一行中记录多个常量吗？

Can I document multiple constants in a single line?

python-sphinx