Welche Sphinx Code-Block-Sprache für JSON verwenden

Question

Ich verwende Sphinx, um einen Web-Service zu dokumentieren. Ich würde gerne eine formatierte JSON-Web-Antwort mit der Code-Block-Direktive zeigen, die Spinx über Pygments macht, aber JSON hat keinen Syntax-Highlighter in den Segmenten. Welche Sprache schlägst du stattdessen vor? HTML? JavaScript?

.. code-block:: javascript 

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

Answer 1

JSON ist JavaScript, schlicht und einfach. JSON steht tatsächlich für "JavaScript Object Notation".

Answer 2

Ich war nicht glücklich mit Pygmente Javascript für die Analyse von JSON. Ja, JSON kann vom JavaScript-Lexer analysiert werden, aber JavaScript-Highlighting ist nicht sehr nützlich, wenn es auf einen JSON-Wert angewendet wird. Normalerweise erhältst du einen riesigen Klumpen undifferenzierten Text.

Da ich keine gute Lösung finden konnte, habe ich eine JSON lexer for pygments erstellt. Ich benutze es jetzt, um JSON in sphinx erstellten PDF-Dokumenten hervorzuheben. Es ist nicht perfekt, aber die Ergebnisse sind viel nützlicher als mit dem Javascript-Lexer. Ich hoffe, es hilft.

Answer 3

Sogar mit Sphinx 1.2b1 und Segments 1.6, musste ich add_lexer aufrufen, um .. code-block:: json zu bekommen, irgendetwas zu machen. Ich beendete das folgende Codefragment in eine Erweiterung nach oben setzen (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()) 

Meine docs/conf.py für Sphinx hat die folgende, um die Erweiterung zu aktivieren:

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

Ich verwende Sphinx 1.4.2 die enthält einen Pygmente-Lexer namens "json". Dies ist standardmäßig out-of-the-box verfügbar. Zu verwenden:

.. code-block:: json 

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