ReadTheDocs 系统的代码格式

Question

我是第一次使用 Read the Docs。我正在为命令行系统编写文档，我的 "code samples" 包含 shell 输出日志。 shell 输出最终看起来像这样

也就是说——该服务（或我对它的使用？）正试图将这个运行示例格式化为一个 shell 命令，就好像它是源代码一样，并且正在处理 magento2:generate 就好像它是一个 class 常量。

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

Answer 1

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

狮身人面像

对于 Sphinx，您可以使用 code-block 指令并包含块的 "language"：

.. code-block:: console

    You shell commands go here

在上面的示例中，我使用 console 作为 shell session. The alias shell-session would work as well. Note that the alternative lexer bash（及其别名：sh、ksh、zsh 和 shell) 严格来说并不适合 shell 脚本，而您在 shell 会话中同时显示命令和输出。

可在 Pygments 文档中找到受支持 language codes 的完整列表。

MkDocs

MkDocs 使用 Fenced Code Block Markdown 扩展来定义代码块的 "language":

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

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

ReadTheDocs 系统的代码格式

Code Formatting for the ReadTheDocs System

magento

python-sphinx

read-the-docs

mkdocs

狮身人面像

MkDocs