JSON 使用哪种 Sphinx 代码块语言答案

【问题标题】：Which Sphinx code-block language to use for JSONJSON 使用哪种 Sphinx 代码块语言
【发布时间】：2011-05-14 15:10:43
【问题描述】：

我正在使用 Sphinx 来记录 Web 服务。我想使用代码块指令显示格式化的 JSON Web 响应，这是 Spinx 通过 Pygments 完成的，但 JSON 在 Pygments 中没有语法高亮显示。你建议我指定什么语言？ HTML？ JavaScript？

.. code-block:: javascript

    {
      "name": "roger",
      "score": 100
    }

【问题讨论】：

标签： pygments python-sphinx

【解决方案1】：

我正在使用 Sphinx 1.4.2，其中包含一个名为“json”的 Pygments 词法分析器。默认情况下，这是开箱即用的。使用方法：

.. code-block:: json

    {
        "key": "value",
        "key2": "value2",
        ...
    }

【讨论】：

事实上，它从 Pygments 1.5 版开始可用。 Source

【解决方案2】：

我不喜欢使用 pygments javascript 来解析 JSON。是的，javascript 词法分析器可以解析 JSON，但是当应用于 JSON 值时，javascript 突出显示不是很有用。您通常会得到一大堆未区分的文本。

由于找不到好的解决方案，我创建了一个JSON lexer for pygments。我现在使用它在 sphinx 创建的 PDF 文档中突出显示 JSON。它并不完美，但结果比使用 javascript 词法分析器更有用。希望对你有帮助。

【讨论】：

用于 pygments 的 JSON 词法分析器现在在 Pygments >= 1.5 中，但似乎也需要一些 Sphinx 支持，特别是您需要添加一个调用 add_lexer (sphinx-doc.org/ext/…) 的 Sphinx 扩展用于 json （尽管这对于最新版本的 Sphinx 可能不是必需的）。

【解决方案3】：

即使使用 Sphinx 1.2b1 和 Pygments 1.6，我也需要调用 add_lexer 来获取 .. code-block:: json 来做任何事情。我最终将以下代码片段放入扩展中（docs/_ext/jsonlexer.py）：

def setup(app):
    # enable Pygments json lexer
    try:
        import pygments
        if pygments.__version__ >= '1.5':
            # use JSON lexer included in recent versions of Pygments
            from pygments.lexers import JsonLexer
        else:
            # use JSON lexer from pygments-json if installed
            from pygson.json_lexer import JSONLexer as JsonLexer
    except ImportError:
        pass  # not fatal if we have old (or no) Pygments and no pygments-json
    else:
        app.add_lexer('json', JsonLexer())

我的 docs/conf.py 用于 Sphinx 具有以下启用扩展功能：

import os
import sys

sys.path.insert(0, os.path.abspath('_ext'))

# Add any Sphinx extension module names here, as strings. They can be
# extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['jsonlexer']

【讨论】：

这是一个很好的答案，激发了用户构建他们的自定义样式。

【解决方案4】：

JSON 是 JavaScript，简单明了。 JSON 实际上代表“JavaScript Object Notation”。

【讨论】：

是的，我知道。只是想知道其他人是否也在 Sphinx 中使用 javascript Pygments 荧光笔进行 JSON 标记，或者是否有其他推荐的语言。
Gabriel 说 JSON 语法是 JavaScript 语法的严格子集，因此任何适用于 JavaScript 的语法高亮器也将处理 JSON。
谢谢乔，只是为了向 OP 澄清一下：JavaScript 荧光笔是正确使用的，没有 JSON 特定的荧光笔（因为 JSON is JavaScript）， Sphinx 中没有更好的选择来突出显示 JSON。

【解决方案5】：

Sphinx 默认提供了几个专用于 JSON 高亮的 pygment 词法分析器，所以你可以在这里选择一个：

http://pygments.org/docs/lexers/#lexers-for-data-file-format

pygments.lexers.data.JsonLexer (pygment v1.5+)

对于 JSON 数据结构。
```
.. code-block:: json
```
pygments.lexers.data.JsonLdLexer (pygment v2.0+)

对于JSON-LD 链接数据。
```
.. code-block:: json-ld
```
pygments.lexers.data.JsonBareObjectLexer (pygment v2.2+)

对于 JSON 数据结构（缺少对象花括号）。
```
.. code-block:: json-object
```

【讨论】：