From 7c625e983f4b1c7cca20c4d38de59ffdcbe6f201 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 03 2015 08:02:12 +0000 Subject: [PATCH 1/7] Move the api.rst into pagure/doc/api.rst This way we include the API documentation within the sources --- diff --git a/doc/api.rst b/doc/api.rst index 265345d..8edbf23 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -1,64 +1,5 @@ -Pagure API v0 Reference -======================= +Pagure API +========== -Overview --------- - -This documentation describes the Pagure API v0. - -Authentication -~~~~~~~~~~~~~~ - -To access some endpoints, you need login Pagure using API token. You can -generate one in the project setting page. - -When sending HTTP request, include ``Authorization`` field in the header -with value ``token $your-api-token``, where ``$your-api-token`` is the -API token generated in the project setting page. - -Anyone with the token can access the APIs on your behalf, so please be -sure to keep it private and safe. - -Request Encoding -~~~~~~~~~~~~~~~~ - -The payload of POST and GET requests is encoded as -``application/x-www-form-urlencoded``. This is an example URL of a GET -request: -``https://pagure.io/api/0/test/issues?status=Open&tags=Pagure&tags=Enhancement`` - -Return Encoding -~~~~~~~~~~~~~~~ - -The return value of API calls is ``application/json``. This is an -example of return value: - -:: - - { - "args": { - "assignee": null, - "author": null, - "status": null, - "tags": [] - }, - "issues": [ - { - "assignee": null, - "blocks": [], - "comments": [], - "content": "Sample ticket", - "date_created": "1434266418", - "depends": [], - "id": 4, - "private": false, - "status": "Open", - "tags": [], - "title": "This is a sample", - "user": { - "fullname": "Pagure", - "name": "API" - } - } - ] - } +The API documentation can be found at https://pagure.io/api/0/ or within +the sources in ``pagure/doc/api.rst``. diff --git a/pagure/doc/api.rst b/pagure/doc/api.rst new file mode 100644 index 0000000..265345d --- /dev/null +++ b/pagure/doc/api.rst @@ -0,0 +1,64 @@ +Pagure API v0 Reference +======================= + +Overview +-------- + +This documentation describes the Pagure API v0. + +Authentication +~~~~~~~~~~~~~~ + +To access some endpoints, you need login Pagure using API token. You can +generate one in the project setting page. + +When sending HTTP request, include ``Authorization`` field in the header +with value ``token $your-api-token``, where ``$your-api-token`` is the +API token generated in the project setting page. + +Anyone with the token can access the APIs on your behalf, so please be +sure to keep it private and safe. + +Request Encoding +~~~~~~~~~~~~~~~~ + +The payload of POST and GET requests is encoded as +``application/x-www-form-urlencoded``. This is an example URL of a GET +request: +``https://pagure.io/api/0/test/issues?status=Open&tags=Pagure&tags=Enhancement`` + +Return Encoding +~~~~~~~~~~~~~~~ + +The return value of API calls is ``application/json``. This is an +example of return value: + +:: + + { + "args": { + "assignee": null, + "author": null, + "status": null, + "tags": [] + }, + "issues": [ + { + "assignee": null, + "blocks": [], + "comments": [], + "content": "Sample ticket", + "date_created": "1434266418", + "depends": [], + "id": 4, + "private": false, + "status": "Open", + "tags": [], + "title": "This is a sample", + "user": { + "fullname": "Pagure", + "name": "API" + } + } + ] + } From ea3e81dc6d21538b5163c9cec1fe19a8a83b1983 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 03 2015 08:02:52 +0000 Subject: [PATCH 2/7] Display the main API documentation in the api endpoint --- diff --git a/pagure/api/__init__.py b/pagure/api/__init__.py index 4c2e2e1..257f9cd 100644 --- a/pagure/api/__init__.py +++ b/pagure/api/__init__.py @@ -10,10 +10,14 @@ API namespace version 0. """ +import codecs import functools +import os -import flask +import docutils import enum +import flask +import markupsafe API = flask.Blueprint('api_ns', __name__, url_prefix='/api/0') @@ -21,10 +25,28 @@ API = flask.Blueprint('api_ns', __name__, url_prefix='/api/0') import pagure import pagure.lib from pagure import __api_version__, APP, SESSION -from pagure.doc_utils import load_doc +from pagure.doc_utils import load_doc, modify_rst, modify_html from pagure.exceptions import APIError +def preload_docs(endpoint): + ''' Utility to load an RST file and turn it into fancy HTML. ''' + + here = os.path.dirname(os.path.abspath(__file__)) + fname = os.path.join(here, '..', 'doc', endpoint + '.rst') + with codecs.open(fname, 'r', 'utf-8') as f: + rst = f.read() + + rst = modify_rst(rst) + api_docs = docutils.examples.html_body(rst) + api_docs = modify_html(api_docs) + api_docs = markupsafe.Markup(api_docs) + return api_docs + + +APIDOC = preload_docs('api') + + class APIERROR(enum.Enum): """ Clast listing as Enum all the possible error thrown by the API. """ @@ -412,6 +434,7 @@ def api(): return flask.render_template( 'api.html', + api_doc=APIDOC, projects=[ api_git_tags_doc, ], diff --git a/pagure/templates/api.html b/pagure/templates/api.html index 71cb2e5..a6be470 100644 --- a/pagure/templates/api.html +++ b/pagure/templates/api.html @@ -6,6 +6,10 @@ {% block content %} +{{ api_doc }} + +

List of the API endpoints:

+

Projects From e3b7cefb5a94b0cde05a28ee382a18005fbc232d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 03 2015 08:12:45 +0000 Subject: [PATCH 3/7] Adjust the API documentation Set the main title and the overview in the html directly which allows to use h2 titles instead of having h1 everywhere. --- diff --git a/pagure/doc/api.rst b/pagure/doc/api.rst index 265345d..12d4ac7 100644 --- a/pagure/doc/api.rst +++ b/pagure/doc/api.rst @@ -1,11 +1,3 @@ -Pagure API v0 Reference -======================= - -Overview --------- - -This documentation describes the Pagure API v0. - Authentication ~~~~~~~~~~~~~~ @@ -16,6 +8,12 @@ When sending HTTP request, include ``Authorization`` field in the header with value ``token $your-api-token``, where ``$your-api-token`` is the API token generated in the project setting page. +So the result should look like: + +:: + + Authorization: token $your-api-token + Anyone with the token can access the APIs on your behalf, so please be sure to keep it private and safe. @@ -23,8 +21,9 @@ Request Encoding ~~~~~~~~~~~~~~~~ The payload of POST and GET requests is encoded as -``application/x-www-form-urlencoded``. This is an example URL of a GET -request: +``application/x-www-form-urlencoded``. + +This is an example URL of a GET request: ``https://pagure.io/api/0/test/issues?status=Open&tags=Pagure&tags=Enhancement`` Return Encoding diff --git a/pagure/templates/api.html b/pagure/templates/api.html index a6be470..c7d7ed1 100644 --- a/pagure/templates/api.html +++ b/pagure/templates/api.html @@ -6,7 +6,10 @@ {% block content %} -{{ api_doc }} +

Pagure API Reference

+

This documentation describes the Pagure API v0.

+ +{{ api_doc |replace('h1', 'h2') }}

List of the API endpoints:

From ec077bb147c5ebbb8d19607bf2e8ca7f60d5dd07 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 03 2015 08:19:54 +0000 Subject: [PATCH 4/7] Add the missing link image used for the anchors --- diff --git a/pagure/static/link.png b/pagure/static/link.png new file mode 100644 index 0000000..1a0d58a Binary files /dev/null and b/pagure/static/link.png differ From ff6342a210413d0f095b075b3e32af2a72ba769e Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 03 2015 08:20:08 +0000 Subject: [PATCH 5/7] Drop the class="headerlink" as it does more harm than good for us here --- diff --git a/pagure/templates/api.html b/pagure/templates/api.html index c7d7ed1..b6ee060 100644 --- a/pagure/templates/api.html +++ b/pagure/templates/api.html @@ -15,7 +15,7 @@

Projects - +

@@ -27,7 +27,7 @@

Issues - +

@@ -39,7 +39,7 @@

Pull-requests - +

@@ -51,7 +51,7 @@

Users - +

@@ -63,7 +63,7 @@

Extras - +

From 93e6e22fe8913642b39a0028487067ba0a292e10 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 03 2015 08:23:59 +0000 Subject: [PATCH 6/7] Add the link image/anchor to accordion-links --- diff --git a/pagure/static/pagure.css b/pagure/static/pagure.css index 8cbebf6..0541d7a 100644 --- a/pagure/static/pagure.css +++ b/pagure/static/pagure.css @@ -206,6 +206,16 @@ header h1 span { display: block; } +.ui-accordion .accordion-link { + position: absolute; + right: 2%; + margin-top: 12px; /* adjust as needed to vertically center the icon */ + z-index: 1; + width: 12px; /* approx 12x12 link icon */ + height: 12px; + background: url(link.png) center center no-repeat; +} + .project_name { font-weight: bold; margin: .5em 0; From fa0fbc8715b444d7aed6d278699d9e80d06d1525 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 03 2015 12:50:53 +0000 Subject: [PATCH 7/7] Adjust the documentation based on the feedback from @puiterwijk --- diff --git a/pagure/doc/api.rst b/pagure/doc/api.rst index 12d4ac7..39db019 100644 --- a/pagure/doc/api.rst +++ b/pagure/doc/api.rst @@ -1,10 +1,10 @@ Authentication ~~~~~~~~~~~~~~ -To access some endpoints, you need login Pagure using API token. You can -generate one in the project setting page. +To access some endpoints, you need to login to Pagure using API token. You +can generate one in the project setting page. -When sending HTTP request, include ``Authorization`` field in the header +When sending HTTP request, include an ``Authorization`` field in the header with value ``token $your-api-token``, where ``$your-api-token`` is the API token generated in the project setting page. @@ -12,7 +12,9 @@ So the result should look like: :: - Authorization: token $your-api-token + Authorization: token abcdefghijklmnop + +Where ``abcdefghijklmnop`` is the API token provided by pagure. Anyone with the token can access the APIs on your behalf, so please be sure to keep it private and safe.