Which Sphinx code-block language to use for JSON

Question

I am using Sphinx to document a web service. I would like to show a formatted JSON web response using the code-block directive, which Spinx does via Pygments, but JSON doesn't have a syntax highlighter in Pygments. What language do you suggest I specify instead? HTML? JavaScript?

.. code-block:: javascript

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

score 27 · Answer 1 · answered Jul 01 '16 at 14:10

27

I am using Sphinx 1.4.2 which includes a Pygments lexer called "json". This is available out-of-the-box by default. To use:

.. code-block:: json

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

answered Jul 01 '16 at 14:10

The Aelfinn

13,649
2
54
45

In fact it is available starting from Pygments version 1.5. [Source](http://pygments.org/docs/lexers/#pygments.lexers.data.JsonLexer) – tomasbedrich Sep 07 '16 at 22:43

score 6 · Answer 2 · answered May 31 '13 at 18:03

Even with Sphinx 1.2b1 and Pygments 1.6, I needed to call add_lexer to get .. code-block:: json to do anything. I ended up putting the following code fragment into an extension (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.py for Sphinx has the following to enable the extension:

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']

It is an excellent answer that inspired the user to build their custom style. — Carson, May 27 '20 at 07:13

score 6 · Answer 3 · answered Aug 28 '11 at 04:41

6

I wasn't happy using pygments javascript for parsing JSON. Yes, JSON can be parsed by the javascript lexer, but javascript highlighting is not very useful when applied to a JSON value. You typically get a giant blob of undifferentiated text.

Since I couldn't find a good solution, I created a JSON lexer for pygments. I'm using it now for highlighting JSON in sphinx created PDF document. It's not perfect, but the results are much more useful than with the javascript lexer. I hope it helps.

answered Aug 28 '11 at 04:41

Norman Richards

1,616
2
11
6

1

JSON lexer for pygments is now in Pygments >= 1.5, but there seems to be a need for some Sphinx support as well, specifically you need to add a Sphinx extension that calls add_lexer (http://sphinx-doc.org/ext/appapi.html#sphinx.application.Sphinx.add_lexer) for json (although this may not be necessary for latest version of Sphinx). – Alex Dupuy May 31 '13 at 16:21

score 3 · Answer 4 · answered Nov 25 '10 at 22:07

3

JSON is JavaScript, plain and simple. JSON in fact stands for "JavaScript Object Notation".

answered Nov 25 '10 at 22:07

Gabriel Hurley

39,690
13
62
88

Yep, knew that. Just wondering if others used the javascript Pygments highlighter for JSON markup in Sphinx too or if there was another recommended language. – JayhawksFan93 Nov 27 '10 at 01:20
Gabriel's saying that JSON syntax is a strict subset of JavaScript syntax, so any proper syntax highlighter for JavaScript will also handle JSON. – Joe Holloway Dec 16 '10 at 17:41
Thanks Joe, and just to clarify to the OP: the JavaScript highlighter is the correct one to use, there is no JSON-specific highlighter (because JSON *is* JavaScript), and there's no better option in Sphinx for highlighting JSON. – Gabriel Hurley Dec 16 '10 at 21:40

score 2 · Answer 5 · answered Jun 21 '18 at 08:41

There is several pygment lexers dedicated to JSON highlighting provided by default with Sphinx, so you can choose one here:

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

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

For JSON data structures.
```
.. code-block:: json
```
pygments.lexers.data.JsonLdLexer (pygment v2.0+)

For JSON-LD linked data.
```
.. code-block:: json-ld
```
pygments.lexers.data.JsonBareObjectLexer (pygment v2.2+)

For JSON data structures (with missing object curly braces).
```
.. code-block:: json-object
```

`.. code-block:: json-object` saved my day! – Andreas L. Mar 08 '22 at 16:59 — Andreas L., Mar 08 '22 at 16:59

Which Sphinx code-block language to use for JSON

5 Answers5