magento - ReadTheDocs 系统的代码格式

Question

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

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

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

Answer 1

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

狮身人面像

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

.. code-block:: console

    You shell commands go here

在上面的示例中，我使用 console 来处理 shell session 。别名 shell-session 也可以工作。请注意，替代词法分析器 bash (及其别名:sh、ksh、zsh 和 shell)严格来说并不适合它们对于 shell 脚本，而您在 shell session 中同时显示命令和输出。

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

MkDocs

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

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

正如 MkDocs 使用 highlight.js与 Pygments 不同，支持的语言列表不同。因此，我在上面的示例中使用了 shell (用于 shell session )。