pygments - JSON 使用哪种 Sphinx 代码块语言

Question

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

.. code-block:: javascript

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

Answer 1

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

.. code-block:: json

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

Answer 2

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

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

Answer 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())

My docs/conf.pyfor 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']

Answer 4

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

Answer 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