ReadTheDocs 系统的代码格式

Question

我是第一次使用“阅读文档” 。我正在为命令行系统编写文档，我的“代码示例”包括 shell 输出的日志。shell 输出最终看起来像这样

也就是说，服务（或者我对它的使用？）正在尝试将运行 shell 命令的示例格式化为源代码，并将视为magento2:generate类常量。

我可以控制哪些代码块在阅读文档时获取源代码格式吗？我尝试在管理中不设置基本语言，但似乎没有效果。或者这是我需要在 sphinx 级别的 mkdocs 中控制的东西？（通过将 Markdown 或 sphinx 文件转换为漂亮的 HTML 文件来阅读文档）或者其他什么？还是我运气不好？

Answer 1

您需要在源文档中定义代码块的“语言”。Sphinx 和 MkDocs 都会尝试猜测语言，这通常就足够了。然而，有时它会猜测错误并导致奇怪的突出显示。为了避免这种情况，两种实现都提供了一种手动定义每个代码块的语言的机制。

狮身人面像

对于 Sphinx，您可以使用code-block指令并包含块的“语言”：

.. code-block:: console

    You shell commands go here

在上面的示例中，我使用了shellconsole会话。别名也可以工作。请注意，替代词法分析器（及其别名：、、和）严格来说并不适合 shell 脚本，而您在 shell 会话中同时显示命令和输出。shell-sessionbashshkshzshshell

支持的语言代码的完整列表可以在 Pygments 文档中找到。

MkDocs 使用Fenced Code Block Markdown 扩展来定义代码块的“语言”：

``` shell
Your shell commands go here
```

由于 MkDocs 使用highlight.js而不是 Pygments，因此支持的语言列表有所不同。因此，我shell在上面的示例中使用了（对于 shell 会话）。