From 57ad64fae6d69569e46e3c73bff2d07987a34273 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Fri, 15 Apr 2016 10:48:31 +0100 Subject: [PATCH] Get the docs rendering in the app MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit replaces the old _API Documentation_ page with the Markdown version that Catherine has been working on. I’ve checked that there’s nothing obviously wrong or placeholder-y still in there, so I think we’re good to go. --- app/main/views/api_keys.py | 5 - app/main/views/index.py | 16 ++- app/templates/views/documentation.html | 141 +------------------------ requirements.txt | 1 + 4 files changed, 19 insertions(+), 144 deletions(-) diff --git a/app/main/views/api_keys.py b/app/main/views/api_keys.py index f50bd0390..aad602179 100644 --- a/app/main/views/api_keys.py +++ b/app/main/views/api_keys.py @@ -6,11 +6,6 @@ from app import api_key_api_client from app.utils import user_has_permissions -@main.route("/documentation") -def documentation(): - return render_template('views/documentation.html') - - @main.route("/services//api-keys") @login_required @user_has_permissions('manage_api_keys') diff --git a/app/main/views/index.py b/app/main/views/index.py index 9b00d14e8..28959a9ef 100644 --- a/app/main/views/index.py +++ b/app/main/views/index.py @@ -1,8 +1,10 @@ -from flask import render_template, url_for, redirect, jsonify +import markdown +from flask import render_template, url_for, redirect, Markup from app.main import main from flask_login import login_required from flask.ext.login import current_user +from mdx_gfm import GithubFlavoredMarkdownExtension @main.route('/') @@ -36,3 +38,15 @@ def pricing(): @main.route('/terms') def terms(): return render_template('views/terms-of-use.html') + + +@main.route('/documentation') +def documentation(): + with open('docs/index.md') as source: + return render_template( + 'views/documentation.html', + body=Markup(markdown.markdown( + source.read(), + extensions=[GithubFlavoredMarkdownExtension()] + )) + ) diff --git a/app/templates/views/documentation.html b/app/templates/views/documentation.html index 60bcf046d..2fba0f113 100644 --- a/app/templates/views/documentation.html +++ b/app/templates/views/documentation.html @@ -1,6 +1,4 @@ {% extends "withoutnav_template.html" %} -{% from "components/page-footer.html" import page_footer %} -{% from "components/api-key.html" import api_key %} {% block page_title %} API documentation – GOV.UK Notify @@ -8,143 +6,10 @@ {% block maincolumn_content %} -

- Developer documentation -

-
-
- -

- How to integrate GOV.UK Notify into your service -

- -

- Notify provides an API that allows the creation of text notifications and the ability to get the status of a - sent notification. -

- -

- API authentication -

- -

- 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" -} - '''|syntax_highlight_json}} - -

Notify application specific:

- {{""" -{ - iss: 'string', // service id - iat: 0, // creation time in epoch seconds (UTC) -} - """|syntax_highlight_json}} -
-
- -

- API endpoints -

- -

To create a text notification

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

- Where ‘to’ is the phone number and ‘template’ is the template ID to send. -

- -

- Response: -

-
-
- {{""" -{ - 'data':{ - 'notification': { - 'id':1 - } - } -} - """|syntax_highlight_json }} - - -

To get the status of a text notification

- - {{ "GET /notifications/{id}"|syntax_highlight_json }} - - {{""" -{ - 'data':{ - '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 -

- -

A python client library is support by the Notify team:

- -

- GOV.UK Notify Python client -

- -

- This provides example code for calling the API and for constructing the API tokens. -

- -

API code

- -

Notify API code is open sourced at:

- -

- GOV.UK Notify API -

- -

API endpoint

- -

- https://api.notifications.service.gov.uk/ -

- -
+
+ {{ body }} +
{% endblock %} diff --git a/requirements.txt b/requirements.txt index c1383edab..baee19ae2 100644 --- a/requirements.txt +++ b/requirements.txt @@ -11,6 +11,7 @@ Flask-Bcrypt==0.6.2 credstash==1.8.0 boto3==1.2.3 Pygments==2.0.2 +py-gfm==0.1.2 git+https://github.com/alphagov/notifications-python-client.git@0.5.0#egg=notifications-python-client==0.5.0