From 7e8046be47e004ad3d7cdecdff7271c62914c5ed Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Tue, 9 Feb 2016 10:28:12 +0000 Subject: [PATCH] Add syntax highlighting to code examples in docs Uses the Pygments[1] package. 1. http://pygments.org/ --- app/__init__.py | 8 ++ app/assets/stylesheets/app.scss | 5 + app/templates/views/documentation.html | 132 +++++++++++++------------ requirements.txt | 1 + 4 files changed, 85 insertions(+), 61 deletions(-) diff --git a/app/__init__.py b/app/__init__.py index 7e34c6c64..e5216b4ad 100644 --- a/app/__init__.py +++ b/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) diff --git a/app/assets/stylesheets/app.scss b/app/assets/stylesheets/app.scss index 19c15a659..dcb2a9f2b 100644 --- a/app/assets/stylesheets/app.scss +++ b/app/assets/stylesheets/app.scss @@ -57,3 +57,8 @@ a { } } + +.highlight { + font-family: monospace; + overflow-x: scroll; +} diff --git a/app/templates/views/documentation.html b/app/templates/views/documentation.html index 4d9c5a648..bc9723c39 100644 --- a/app/templates/views/documentation.html +++ b/app/templates/views/documentation.html @@ -13,7 +13,7 @@
-
+

How to integrate GOV.UK Notify into your service @@ -32,22 +32,28 @@ Notify uses JSON Web Tokens (JWT) for authentication. JWT tokens have a series of claims, standard and application specific.

- +

+

Notify standard claims:

- 
-            typ: JWT
-            alg: HS256
-
+ {{''' +{ + "typ": "JWT", + "alg": "HS256" +} + '''|syntax_highlight_json}}

Notify application specific:

- 
-            iss: service id
-            iat: creation time in  epoch seconds (UTC)
-            req: signed request
-            pay: signed payload (POST requests only)
-
- + {{""" +{ + iss: 'string', // service id + iat: 0, // creation time in epoch seconds (UTC) + req: 'string', // signed request + pay: 'string', // signed payload (POST requests only) +} + """|syntax_highlight_json}} +
+

Notify API tokens sign both the request being made, and for POST requests, the payload.

@@ -56,7 +62,7 @@

Request signing is of the form HTTP METHOD PATH.

- GET /notification/1234 + {{ "GET /notification/1234"|syntax_highlight_json }}

@@ -68,64 +74,68 @@

To create a text notification

+
+
+ {{ "POST /notifications/sms"|syntax_highlight_json }} - POST /notifications/sms - + {{ + """ +{ + 'to': '+441234123123', + 'template': 1 +} + """|syntax_highlight_json + }} +
+

- 

-                {
-                    'to': '+441234123123',
-                    'template': 1
-                }
-
- Where 'to' is the phone number and 'template' is the template id to send. + Where ‘to’ is the phone number and ‘template’ is the template ID to send.

- Response: - 

-                {
-                    'notification':
-                    {
-                        'to': '+441234123123',
-                        'createdAt': '2016-01-01T09:00:00.999999Z',
-                        'status': 'created',
-                        'id': 1,
-                        'message': '....',
-                        'method': 'sms',
-                        'jobId': 1
-                    }
-                }
-
+ Response:

+
+
+ {{""" +{ + 'notification': + { + 'to': '+441234123123', + 'createdAt': '2016-01-01T09:00:00.999999Z', + 'status': 'created', + 'id': 1, + 'message': '....', + 'method': 'sms', + 'jobId': 1 + } +} + """|syntax_highlight_json }} +

To get the status of a text notification

-

- - GET /notifications/{id} - -

+ {{ "GET /notifications/{id}"|syntax_highlight_json }} -

- 

-            {
-                'notification':
-                {
-                    'status': 'sent',
-                    'createdAt': '2016-01-01T09:00:00.999999Z',
-                    'to': '+447827992607',
-                    'method': 'sms',
-                    'sentAt': '2016-01-01T09:01:00.999999Z',
-                    'id': 1,
-                    'message': '...',
-                    'jobId': 1,
-                    'sender': 'sms-partner'
-                }
-            }
-
-

+ {{""" +{ + 'notification': + { + 'status': 'sent', + 'createdAt': '2016-01-01T09:00:00.999999Z', + 'to': '+447827992607', + 'method': 'sms', + 'sentAt': '2016-01-01T09:01:00.999999Z', + 'id': 1, + 'message': '...', + 'jobId': 1, + 'sender': 'sms-partner' + } +} + """|syntax_highlight_json }} +
+

API client libraries

diff --git a/requirements.txt b/requirements.txt index d65172e47..e434c68f2 100644 --- a/requirements.txt +++ b/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