在 Sphinx 代码块中显示用户可修改的文本

Question

使用 Sphinx 记录 shell 命令行示例时，是否有显示用户可修改文本的好方法？例如，什么是显示 <file to delete> 的好方法是用户应该指定而不是逐字键入

Delete a File
`````````````

This is how to delete a file

.. code-block:: console

  $ rm <file to delete>

在其他文档系统中，此文本可能是斜体，但使用 code-block 似乎会禁用所有（大多数？）内联格式。

Answer 1

惯例是使用 ALL_CAPS，将空格替换为下划线 _，用于用户替换。此约定也用于 shell 脚本中的环境变量。

.. code-block:: console

    $ rm FILE_TO_DELETE

不幸的是，据我所知，没有任何词法分析器可以创建足够的 HTML 标记，可以使用自定义 CSS 设置样式。您可以尝试其他 lexers for shells than console, such as bash, but it also is suboptimal. Try the demo 并查看生成的 HTML 标记。

Google's developer documentation style guide 有很好的例子说明我认为应该如何格式化命令行语句。

如果 none 的可用词法分析器令人满意，我建议您 write your own lexer 完全按照您的意愿行事。

在 Sphinx 代码块中显示用户可修改的文本

Show user-modifiable text in Sphinx code-block

python-sphinx