如何在 reStructuredText 指令选项中指定空格或空字符串？

Question

我想要一个空字符串或一个空格作为标题 - 我该怎么做？

.. code-block:: c
   :name: forever
   :caption: ""

   for (;;)
   {
     ;
   }

这不起作用，我收到一条错误消息；如果我使用

" "

引号会出现在我的输出中。

Answer 1

首先，让我回答标题中的一般问题，请参阅下面示例中的具体用例。

rST 标记规范 规定：“指令选项使用字段列表指示；字段名称和内容是特定于指令的。” 字段列表可能有一个空的 field_body，因此空字符串的最简单输入就是空字符串。

一个有效的例子是

.. image:: foo.png
   :alt:

空字符串会覆盖值（图像 URI），HTML 浏览器在渲染 HMTL 输出时将默默地忽略丢失的图像。

其他选项（例如：class：或“sidebar”指令的：subtitle：）在没有值的情况下使用时会引发异常。这也适用于 Sphinx 添加的“代码块”指令中的 :caption: 。

然而， :caption: 值被解析为内联 reStructuredText（不幸的是，详细信息未记录），因此不生成可见输出的构造可用于获取空标题。 这也解决了

__

 导致所需结果的难题，因为它是匿名 hyperref 目标的 rST 语法（您通常会因不平衡的匿名引用和目标而收到的错误消息似乎已被抑制）。

我的建议是使用空的注释：

.. code-block:: c
   :name: forever
   :caption: ..

   for (;;) { ; }

另一种方法是定义并使用空格字符的替换，例如

.. |space| unicode:: 32 

.. code-block:: c
   :name: forever
   :caption: |space|

   for (;;) { ; }

️与标准 rST 块相比，

..

 之后的内容不会受到抑制。