Add syntax highlighting to code examples in docs

Uses the Pygments[1] package.

1. http://pygments.org/

app/__init__.py

@@ -9,6 +9,9 @@ from flask.ext.sqlalchemy import SQLAlchemy
 from flask_login import LoginManager
 from flask_wtf import CsrfProtect
 from werkzeug.exceptions import abort
+from pygments import highlight
+from pygments.lexers import JavascriptLexer
+from pygments.formatters import HtmlFormatter
 from app.notify_client.api_client import NotificationsAdminAPIClient
 from app.notify_client.api_key_api_client import ApiKeyApiClient
 from app.notify_client.user_api_client import UserApiClient
@@ -61,6 +64,7 @@ def create_app(config_name, config_overrides=None):
     application.add_template_filter(replace_placeholders)
     application.add_template_filter(nl2br)
     application.add_template_filter(format_datetime)
+    application.add_template_filter(syntax_highlight_json)
 
     application.after_request(useful_headers_after_request)
     register_errorhandlers(application)
@@ -144,6 +148,10 @@ def replace_placeholders(template, values):
     ))
 
 
+def syntax_highlight_json(code):
+    return Markup(highlight(code, JavascriptLexer(), HtmlFormatter(noclasses=True)))
+
+
 def format_datetime(date):
     date = dateutil.parser.parse(date)
     native = date.replace(tzinfo=None)

app/assets/stylesheets/app.scss

@@ -57,3 +57,8 @@ a {
   }
 
 }
+
+.highlight {
+  font-family: monospace;
+  overflow-x: scroll;
+}

app/templates/views/documentation.html

@@ -13,7 +13,7 @@
 </h1>
 
 <div class="grid-row">
-    <div class="column-two-thirds">
+    <div class="column-three-quarters">
 
         <h2 class="heading-medium">
             How to integrate GOV.UK Notify into your service
@@ -32,22 +32,28 @@
             Notify uses <a href="https://jwt.io/">JSON Web Tokens (JWT)</a> for authentication.
             JWT tokens have a series of claims, standard and application specific.
         </p>
-
+    </div>
+</div>
         <p>Notify standard claims:</p>
 
-        <pre>
+        {{'''
-            typ: JWT
+{
-            alg: HS256
+  "typ": "JWT",
-        </pre>
+  "alg": "HS256"
+}
+        '''|syntax_highlight_json}}
 
         <p>Notify application specific:</p>
-        <pre>
+        {{"""
-            iss: service id
+{
-            iat: creation time in  epoch seconds (UTC)
+  iss: 'string', // service id
-            req: signed request
+  iat: 0, // creation time in  epoch seconds (UTC)
-            pay: signed payload (POST requests only)
+  req: 'string', // signed request
-        </pre>
+  pay: 'string', // signed payload (POST requests only)
-
+}
+        """|syntax_highlight_json}}
+<div class="grid-row">
+    <div class="column-three-quarters">
         <p>Notify API tokens sign both the request being made, and for POST requests, the payload.</p>
 
         <p>
@@ -56,7 +62,7 @@
 
         <p>Request signing is of the form HTTP METHOD PATH.</p>
 
-        <code>GET /notification/1234</code>
+        {{ "GET /notification/1234"|syntax_highlight_json }}
 
         <p></p>
 
@@ -68,64 +74,68 @@
         </h3>
 
         <p>To create a text notification</p>
+    </div>
+</div>
+        {{ "POST /notifications/sms"|syntax_highlight_json }}
 
-        <code>POST /notifications/sms</code>
+        {{
-
+          """
+{
+  'to': '+441234123123',
+  'template': 1
+}
+          """|syntax_highlight_json
+        }}
+<div class="grid-row">
+    <div class="column-three-quarters">
         <p>
-            <pre>
+          Where ‘to’ is the phone number and ‘template’ is the template ID to send.
-                {
-                    'to': '+441234123123',
-                    'template': 1
-                }
-            </pre>
-        Where 'to' is the phone number and 'template' is the template id to send.
         </p>
 
         <p>
-            Response:
+          Response:
-            <pre>
-                {
-                    'notification':
-                    {
-                        'to': '+441234123123',
-                        'createdAt': '2016-01-01T09:00:00.999999Z',
-                        'status': 'created',
-                        'id': 1,
-                        'message': '....',
-                        'method': 'sms',
-                        'jobId': 1
-                    }
-                }
-            </pre>
         </p>
+    </div>
+</div>
+        {{"""
+{
+  'notification':
+  {
+    'to': '+441234123123',
+    'createdAt': '2016-01-01T09:00:00.999999Z',
+    'status': 'created',
+    'id': 1,
+    'message': '....',
+    'method': 'sms',
+    'jobId': 1
+  }
+}
+        """|syntax_highlight_json }}
+
 
         <p>To get the status of a text notification</p>
 
-        <p>
+        {{ "GET /notifications/{id}"|syntax_highlight_json }}
-            <code>
-                GET /notifications/{id}
-            </code>
-        </p>
 
-        <p>
+        {{"""
-            <pre>
+{
-            {
+  'notification':
-                'notification':
+  {
-                {
+    'status': 'sent',
-                    'status': 'sent',
+    'createdAt': '2016-01-01T09:00:00.999999Z',
-                    'createdAt': '2016-01-01T09:00:00.999999Z',
+    'to': '+447827992607',
-                    'to': '+447827992607',
+    'method': 'sms',
-                    'method': 'sms',
+    'sentAt': '2016-01-01T09:01:00.999999Z',
-                    'sentAt': '2016-01-01T09:01:00.999999Z',
+    'id': 1,
-                    'id': 1,
+    'message': '...',
-                    'message': '...',
+    'jobId': 1,
-                    'jobId': 1,
+    'sender': 'sms-partner'
-                    'sender': 'sms-partner'
+  }
-                }
+}
-            }
+        """|syntax_highlight_json }}
-            </pre>
-        </p>
 
+<div class="grid-row">
+    <div class="column-three-quarters">
         <h2 class="heading-medium">
             API client libraries
         </h2>

requirements.txt

@@ -10,6 +10,7 @@ Flask-Login==0.2.11
 Flask-Bcrypt==0.6.2
 credstash==1.8.0
 boto3==1.2.3
+Pygments==2.0.2
 
 git+https://github.com/alphagov/notifications-python-client.git@0.2.2#egg=notifications-python-client==0.2.2