ReadTheDocs 系统的代码格式答案

【问题标题】：Code Formatting for the ReadTheDocs SystemReadTheDocs 系统的代码格式
【发布时间】：2019-07-03 15:05:09
【问题描述】：

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

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

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

【问题讨论】：

使用 Sphinx 和 reStructuredText，您可以使用 code-block 指令和 sh（或者可能是 console）作为语言。 sphinx-doc.org/en/stable/usage/restructuredtext/…
要添加到@mzjn，Sphinx（RTD 使用）中的语法高亮是通过 Pygments 提供的，带有称为“lexers”的东西。请参阅complete list of lexers。请注意，大多数（但不是全部）都受支持。具体见shell lexers。

标签： magento python-sphinx read-the-docs mkdocs

【解决方案1】：

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

狮身人面像

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

.. code-block:: console

    You shell commands go here

在上面的例子中，我使用了console 作为shell session。别名 shell-session 也可以。请注意，替代词法分析器 bash（及其别名：sh、ksh、zsh 和 shell）并不严格适用于 shell 脚本，而您同时显示了两个命令以及 shell 会话中的输出。

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

MkDocs

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

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

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

【讨论】：