如何在 sphinx 中为生成的代码块设置标题

Question

目前我正在使用以下代码生成代码块并在其中显示一些信息。 我想设置一个标题，就像下面的第一个指令一样。

.. code-block:: python
   :caption: my_file.py

目前我正在使用以下代码，但它

from docutils import nodes
from docutils.parsers.rst import Directive, directives


class ExecuteCode(Directive):

    def run(self):
        output = []
        input_code = nodes.literal_block(shown_code, shown_code)

        # This creates a normal text directly above the code block
        output.append(nodes.caption(text=self.options['header_code']))

        # This doesn't do anything at all
        input_code['caption'] = nodes.caption('asdf', 'asdf')
        
        return output

如何在literal_block上设置标题？

Answer 1

从 Sphinx 1.3 开始，这是

:caption:

指令

文档

示例：

.. code-block:: python
   :caption: my_file.py

   print("Hello world!")

输出示例：

注意：我发现我的编辑器预览器（pycharm 或 vscode）似乎不支持此指令，但是当我构建时，输出文件会按预期显示标题和代码片段。