温馨提示:本文翻译自stackoverflow.com,查看原文请点击:magento - Code Formatting for the ReadTheDocs System
magento python-sphinx read-the-docs mkdocs

magento - ReadTheDocs系统的代码格式

发布于 2020-03-27 11:42:31

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

读取文档的shell输出图像想格式化,就好像它是源代码一样,导致了一些奇怪的选择

就是说-服务(或我对它的使用?)正在尝试格式化运行shell命令的示例,就好像它是源代码一样,并且正在将其magento2:generate视为类常量。

我可以控制哪些代码块在阅读文档时获取源代码格式吗?我试过在管理员中未设置任何基本语言,但似乎没有效果。还是我需要在Sphinx级别的mkdocs上控制这些东西?(通过将markdown或sphinx文件转换为漂亮的HTML文件来阅读文档,可以看到其他内容吗?还是我不走运?

查看更多

查看更多

提问者
Alan Storm
被浏览
64
Waylan 2019-07-10 02:28

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

狮身人面像

对于Sphinx,可以使用code-block指令并包括该的“语言”:

.. code-block:: console

    You shell commands go here

在上面的示例中,我使用consoleshell会话别名shell-session也可以使用。需要注意的是替代词法分析器bash(和它的别名:shkshzsh,和shell),因为它们是一个shell脚本woudl不严格是合适的,而你在一个shell会话同时显示的命令和theoutput。

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

MkDocs

MkDocs利用Fenced 代码块 Markdown扩展来定义代码块的“语言”:

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

作为MkDocs使用highlight.js而非Pygments来做,支持的语言列表是不同的。因此,我shell在上面的示例中使用了(用于shell会话)。