如何解决在 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 完全按照您的意愿行事。
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。