PR#283: Improve online API documentation - pagure

		`@@ -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``.

pagure/api/__init__.py

file modified

+25 -2

		`@@ -10,10 +10,14 @@`

		`"""`

		`+ 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 @@`
		`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 @@`

		`return flask.render_template(`
		`'api.html',`
		`+ api_doc=APIDOC,`
		`projects=[`
		`api_git_tags_doc,`
		`],`

pagure/doc/api.rst

file added

+65

		`@@ -0,0 +1,65 @@`
		`+ Authentication`
		`+ ~~~~~~~~~~~~~~`
		`+`
		`+ 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 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.`
		`+`
		`+ So the result should look like:`
		`+`
		`+ ::`
		`+`
		`+ 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.`
		`+`
		`+ 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"`
		`+ }`
		`+ }`
		`+ ]`
		`+ }`

pagure/static/link.png

file added

empty or binary file added

pagure/static/pagure.css

file modified

+10

		`@@ -206,6 +206,16 @@`
		`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;`

pagure/templates/api.html

file modified

+12 -5

		`@@ -6,9 +6,16 @@`

		`{% block content %}`

		`+ <h1 class="title">Pagure API Reference</h1>`
		`+ <p>This documentation describes the Pagure API v0.</p>`
		`+`
		`+ {{ api_doc \|replace('h1', 'h2') }}`
		`+`
		`+ <h1>List of the API endpoints:</h1>`
		`+`
		`<h2>`
		`Projects`
		`- <a name="projects" class="headerlink" title="Permalink to this headline" href="#projects">`
		`+ <a name="projects" title="Permalink to this headline" href="#projects">`
		`<img src="{{ url_for('static', filename='link.png') }}" />`
		`</a>`
		`</h2>`
		`@@ -20,7 +27,7 @@`

		`<h2>`
		`Issues`
		`- <a name="users" class="headerlink" title="Permalink to this headline" href="#users">`
		`+ <a name="users" title="Permalink to this headline" href="#users">`
		`<img src="{{ url_for('static', filename='link.png') }}" />`
		`</a>`
		`</h2>`
		`@@ -32,7 +39,7 @@`

		`<h2>`
		`Pull-requests`
		`- <a name="users" class="headerlink" title="Permalink to this headline" href="#users">`
		`+ <a name="users"title="Permalink to this headline" href="#users">`
		`<img src="{{ url_for('static', filename='link.png') }}" />`
		`</a>`
		`</h2>`
		`@@ -44,7 +51,7 @@`

		`<h2>`
		`Users`
		`- <a name="users" class="headerlink" title="Permalink to this headline" href="#users">`
		`+ <a name="users" title="Permalink to this headline" href="#users">`
		`<img src="{{ url_for('static', filename='link.png') }}" />`
		`</a>`
		`</h2>`
		`@@ -56,7 +63,7 @@`

		`<h2>`
		`Extras`
		`- <a name="extras" class="headerlink" title="Permalink to this headline" href="#extras">`
		`+ <a name="extras" title="Permalink to this headline" href="#extras">`
		`<img src="{{ url_for('static', filename='link.png') }}" />`
		`</a>`
		`</h2>`