From 5c8d194bd5eda914fe61508b2954b73b939a8575 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: May 29 2015 08:52:23 +0000 Subject: [PATCH 1/9] Start the /api/0/ endpoint documenting the API itself --- diff --git a/pagure/api/__init__.py b/pagure/api/__init__.py index 0cff249..3aa5e31 100644 --- a/pagure/api/__init__.py +++ b/pagure/api/__init__.py @@ -21,6 +21,7 @@ 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.exceptions import APIError @@ -167,6 +168,27 @@ from pagure.api import issue from pagure.api import fork +@API.route('/') +def api(): + ''' Display the api information page. ''' + api_version_doc = load_doc(api_version) + api_users = load_doc(api_users) + api_project_tags = load_doc(api_project_tags) + api_groups = load_doc(api_groups) + api_error_codes = load_doc(api_error_codes) + + return flask.render_template( + 'api.html', + extras=[ + api_version_doc, + api_users, + api_project_tags, + api_groups, + api_error_codes, + ], + ) + + @API.route('/version/') @API.route('/version') def api_version(): From 83a3acf6a4f8b174754929a66d3da8cc20ff5fce Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: May 29 2015 08:52:24 +0000 Subject: [PATCH 2/9] Add the load_doc method in doc_utils --- diff --git a/pagure/doc_utils.py b/pagure/doc_utils.py index ac8032d..0506489 100644 --- a/pagure/doc_utils.py +++ b/pagure/doc_utils.py @@ -11,8 +11,10 @@ import docutils import docutils.core +import docutils.examples import markupsafe import markdown +import textwrap def modify_rst(rst, view_file_url=None): @@ -94,3 +96,18 @@ def convert_readme(content, ext, view_file_url=None): elif not ext or (ext and ext in ['.text', '.txt']): output = '
%s
' % content return output + + +def load_doc(endpoint): + """ Utility to load an RST file and turn it into fancy HTML. """ + + rst = unicode(textwrap.dedent(endpoint.__doc__)) + + 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 From 3578fdd32202f094ea1247877fad6362ff37927b Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: May 29 2015 08:52:24 +0000 Subject: [PATCH 3/9] Add the insertDiv Jinja filter required for the API documentation --- diff --git a/pagure/ui/filters.py b/pagure/ui/filters.py index d0b12f4..0528f24 100644 --- a/pagure/ui/filters.py +++ b/pagure/ui/filters.py @@ -270,3 +270,23 @@ def author_to_avatar(author, size=32): user = pagure.lib.search_user(SESSION, email=author.email) output = user.user if user else author.name return avatar(output, size) + + +@APP.template_filter('InsertDiv') +def insert_div(content): + """ Template filter inserting an opening
and closing
+ after the first title and then at the end of the content. + """ + # This is quite a hack but simpler solution using .replace() didn't work + # for some reasons... + content = content.split('\n') + output = [] + for row in content: + if row.startswith('
', '
') + output = output.replace('h1', 'h3') + + return output From aa08df15c27b46986d952072b5cadbf2be5c530c Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: May 29 2015 08:52:24 +0000 Subject: [PATCH 4/9] Move the API documentation endpoint to be after the declaration of the methods it depends on --- diff --git a/pagure/api/__init__.py b/pagure/api/__init__.py index 3aa5e31..bb639a9 100644 --- a/pagure/api/__init__.py +++ b/pagure/api/__init__.py @@ -168,27 +168,6 @@ from pagure.api import issue from pagure.api import fork -@API.route('/') -def api(): - ''' Display the api information page. ''' - api_version_doc = load_doc(api_version) - api_users = load_doc(api_users) - api_project_tags = load_doc(api_project_tags) - api_groups = load_doc(api_groups) - api_error_codes = load_doc(api_error_codes) - - return flask.render_template( - 'api.html', - extras=[ - api_version_doc, - api_users, - api_project_tags, - api_groups, - api_error_codes, - ], - ) - - @API.route('/version/') @API.route('/version') def api_version(): @@ -370,3 +349,24 @@ def api_error_codes(): errors = {val.name: val.value for val in APIERROR.__members__.values()} return flask.jsonify(errors) + + +@API.route('/') +def api(): + ''' Display the api information page. ''' + api_version_doc = load_doc(api_version) + api_users_doc = load_doc(api_users) + api_project_tags_doc = load_doc(api_project_tags) + api_groups_doc = load_doc(api_groups) + api_error_codes_doc = load_doc(api_error_codes) + + return flask.render_template( + 'api.html', + extras=[ + api_version_doc, + api_users_doc, + api_project_tags_doc, + api_groups_doc, + api_error_codes_doc, + ], + ) From a00a4aed2ec7231bb1d5605afc5f2df1f314a971 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: May 29 2015 08:52:24 +0000 Subject: [PATCH 5/9] Add the api.html template for the API documentation --- diff --git a/pagure/templates/api.html b/pagure/templates/api.html new file mode 100644 index 0000000..c551144 --- /dev/null +++ b/pagure/templates/api.html @@ -0,0 +1,88 @@ +{% extends "master.html" %} + +{% block title %} API | pagure {% endblock %} + +{%block tag %}index{% endblock %} + +{% block content %} + +

+ Projects + + + +

+
+{% for html in projects %} +{{ html | InsertDiv | safe }} +{% endfor %} +
+ +

+ Users + + + +

+
+{% for html in users %} +{{ html | InsertDiv | safe }} +{% endfor %} +
+ +

+ Extras + + + +

+ +
+{% for html in extras %} +{{ html | InsertDiv |safe }} +{% endfor %} +
+ +{% endblock %} + +{% block jscripts %} +{{ super() }} + +{% endblock %} From 92c314deffd78ace23102aca6cf8d46406286163 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: May 29 2015 08:52:24 +0000 Subject: [PATCH 6/9] Add a link to the API documentation in the master template --- diff --git a/pagure/templates/master.html b/pagure/templates/master.html index 4d1de59..9fce4d0 100644 --- a/pagure/templates/master.html +++ b/pagure/templates/master.html @@ -78,7 +78,8 @@ From 47edc6458fb0b2069997e60c7a66867f7e85d37c Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: May 29 2015 08:52:24 +0000 Subject: [PATCH 7/9] Fix title in the api_pull_request_add_comment docstring --- diff --git a/pagure/api/fork.py b/pagure/api/fork.py index d87b032..52b5bd2 100644 --- a/pagure/api/fork.py +++ b/pagure/api/fork.py @@ -412,7 +412,7 @@ def api_pull_request_close(repo, requestid, username=None): def api_pull_request_add_comment(repo, requestid, username=None): """ Comment on a pull-request - -------------------- + ------------------------- This endpoint can be used to comment on a pull-request :: From a514aecb35cf6ec13d43d4e541ea7d22a882fe18 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: May 29 2015 08:52:24 +0000 Subject: [PATCH 8/9] List and organize all the API endpoints --- diff --git a/pagure/api/__init__.py b/pagure/api/__init__.py index bb639a9..367f4c4 100644 --- a/pagure/api/__init__.py +++ b/pagure/api/__init__.py @@ -354,6 +354,15 @@ def api_error_codes(): @API.route('/') def api(): ''' Display the api information page. ''' + api_new_issue_doc = load_doc(issue.api_new_issue) + api_view_issues_doc = load_doc(issue.api_view_issues) + + api_pull_request_views_doc = load_doc(fork.api_pull_request_views) + api_pull_request_view_doc = load_doc(fork.api_pull_request_view) + api_pull_request_merge_doc = load_doc(fork.api_pull_request_merge) + api_pull_request_close_doc = load_doc(fork.api_pull_request_close) + api_pull_request_add_comment_doc = load_doc(fork.api_pull_request_add_comment) + api_version_doc = load_doc(api_version) api_users_doc = load_doc(api_users) api_project_tags_doc = load_doc(api_project_tags) @@ -362,11 +371,22 @@ def api(): return flask.render_template( 'api.html', + projects=[ + api_new_issue_doc, + api_view_issues_doc, + api_pull_request_views_doc, + api_pull_request_view_doc, + api_pull_request_merge_doc, + api_pull_request_close_doc, + api_pull_request_add_comment_doc, + ], + users=[ + api_users_doc, + api_groups_doc, + ], extras=[ api_version_doc, - api_users_doc, api_project_tags_doc, - api_groups_doc, api_error_codes_doc, ], ) From 0d3bf1a53cbec5db9efae9ae12e938df3cf6ca62 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: May 29 2015 08:52:24 +0000 Subject: [PATCH 9/9] Drop the API link at the bottom of the master template until we get to v1 --- diff --git a/pagure/templates/master.html b/pagure/templates/master.html index 9fce4d0..7a43248 100644 --- a/pagure/templates/master.html +++ b/pagure/templates/master.html @@ -79,8 +79,7 @@