如何在figure directive中为长caption换行？使用line blocks后caption消失如何解决

你遇到的line block写caption后内容消失的问题，是reStructuredText的figure指令解析规则导致的：
figure指令后空一行的第一个缩进块，会被解析器识别为图题（caption），而图题只能是单段落的纯文本内容，不能直接嵌套line block、列表这类多段式结构。你直接在第一个缩进块写line block，解析器会判定这段内容不属于图题，导致图题被识别为空，自然就不会显示。

解决方案 #

方案1：兼容HTML/PDF双输出的通用换行方法 #

这个方案对Sphinx的所有输出格式都生效，是最推荐的做法：

1. 先在当前rst文档的顶部，或者项目全局的rst替换定义文件中添加如下换行标记定义：

.. |br| raw:: html

   <br />

2. 调整你的figure写法，在需要换行的位置插入|br|即可：

.. figure:: a.png
   :width: 200

   First line |br|
   second line.

方案2：仅适配LaTeX PDF输出 #

如果你只用reStructuredText生成PDF，不需要兼容HTML格式，可以直接在换行位置插入\\：

.. figure:: a.png
   :width: 200

   First line \\
   second line.

注意事项 #

如果你需要的不是图题内的换行，而是要在图题下方添加多行补充说明，可以把line block内容放在legend块的位置，写法如下，这部分内容会显示在图题下方，样式和图题有区别：

.. figure:: a.png
   :width: 200

   这里写正常的图题内容

   | First line
   | second line.

内容的提问来源于stack exchange，提问作者Shibli