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

问题描述

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

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

This is how to delete a file

.. code-block:: console

  $ rm <file to delete>

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

解决方法

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

.. code-block:: console

    $ rm FILE_TO_DELETE

不幸的是，我所知道的没有词法分析器可以创建足够的 HTML 标记，可以使用自定义 CSS 设置样式。您可以尝试除控制台之外的其他 lexers for shells，例如 bash，但它也是次优的。尝试使用 demo 并查看生成的 HTML 标记。

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

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