From e6fcc6b2800228b9f2092fea8881887aae3154d1 Mon Sep 17 00:00:00 2001
From: Jeremy Cline <jeremy@jcline.org>
Date: Feb 13 2017 11:25:46 +0000
Subject: [PATCH 1/2] Auto-document the REST API


Signed-off-by: Jeremy Cline <jeremy@jcline.org>

---

diff --git a/dev-requirements.txt b/dev-requirements.txt
new file mode 100644
index 0000000..03187c4
--- /dev/null
+++ b/dev-requirements.txt
@@ -0,0 +1,4 @@
+# Docs dependencies
+sphinx
+cloud_sptheme
+sphinxcontrib-httpdomain
diff --git a/doc/api.rst b/doc/api.rst
index 8edbf23..3d55c29 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -1,5 +1,16 @@
 Pagure API
 ==========
 
-The API documentation can be found at https://pagure.io/api/0/ or within
-the sources in ``pagure/doc/api.rst``.
+This documents the APIs Pagure offers.
+
+
+.. _rest-api:
+
+HTTP REST API
+-------------
+
+.. autoflask:: pagure:APP
+   :modules: pagure.api, pagure.api.fork, pagure.api.issue, pagure.api.project,
+             pagure.api.user, pagure.api.ci.jenkins
+   :undoc-static:
+   :order: path
diff --git a/doc/conf.py b/doc/conf.py
index 9af8e95..062b5e1 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -39,7 +39,10 @@ with open(pagurefile) as stream:
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'
+    'sphinx.ext.autodoc',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode',
+    'sphinxcontrib.autohttp.flask',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/doc/index.rst b/doc/index.rst
index d5ea43f..5c1304f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -31,6 +31,7 @@ Contents:
 
    overview
    usage/index
+   api
    install
    install_milter
    install_evs

From 7aa6198acd4f25c2d6d446bd2b7cbcd1d7f2c142 Mon Sep 17 00:00:00 2001
From: Jeremy Cline <jeremy@jcline.org>
Date: Feb 13 2017 11:25:46 +0000
Subject: [PATCH 2/2] Update the project tags and api version API docs


This fixes the Sphinx warnings generated by the Python docblocks in the
``api_version``, ``api_users``, and ``api_project_tags`` functions.

Signed-off-by: Jeremy Cline <jeremy@jcline.org>

---

diff --git a/pagure/api/__init__.py b/pagure/api/__init__.py
index 3bc2f23..9ec65f1 100644
--- a/pagure/api/__init__.py
+++ b/pagure/api/__init__.py
@@ -220,18 +220,9 @@ if pagure.APP.config.get('PAGURE_CI_SERVICES', False):
 @API.route('/version')
 def api_version():
     '''
-    API Version
-    -----------
     Get the current API version.
 
-    ::
-
-        GET /api/0/version
-
-    Sample response
-    ^^^^^^^^^^^^^^^
-
-    ::
+    Sample response::
 
         {
           "version": "1"
@@ -245,35 +236,19 @@ def api_version():
 @API.route('/users')
 def api_users():
     '''
-    List users
-    -----------
-    Retrieve users that have logged into the Paugre instance.
-    This can then be used as input for autocompletion in some forms/fields.
-
-    ::
+    Retrieve users that have logged into the Pagure instance.
 
-        GET /api/0/users
-
-    Parameters
-    ^^^^^^^^^^
-
-    +---------------+----------+---------------+------------------------------+
-    | Key           | Type     | Optionality   | Description                  |
-    +===============+==========+===============+==============================+
-    | ``pattern``   | string   | Optional      | | Filters the starting       |
-    |               |          |               |   letters of the usernames   |
-    +---------------+----------+---------------+------------------------------+
-
-    Sample response
-    ^^^^^^^^^^^^^^^
+    This can then be used as input for autocompletion in some forms/fields.
 
-    ::
+    Sample response::
 
         {
           "total_users": 2,
           "users": ["user1", "user2"]
         }
 
+    :query string pattern: Filters the starting letters of the usernames
+
     '''
     pattern = flask.request.args.get('pattern', None)
     if pattern is not None and not pattern.endswith('*'):
@@ -301,38 +276,43 @@ def api_users():
 @API.route('/fork/<username>/<repo>/tags/')
 def api_project_tags(repo, username=None):
     '''
-    List all the tags of a project
-    ------------------------------
     List the tags made on the project's issues.
 
-    ::
+    Sample request for a repository's tags:
 
-        GET /api/0/<repo>/tags
+    .. sourcecode:: http
 
-    ::
+        GET /api/0/my_repo/tags HTTP/1.1
+        Host: example.com
+        Accept: application/json
 
-        GET /api/0/fork/<username>/<repo>/tags
+    Sample request for the repository tags of a fork:
 
-    Parameters
-    ^^^^^^^^^^
+    .. sourcecode:: http
 
-    +---------------+----------+---------------+--------------------------+
-    | Key           | Type     | Optionality   | Description              |
-    +===============+==========+===============+==========================+
-    | ``pattern``   | string   | Optional      | | Filters the starting   |
-    |               |          |               |   letters of the tags    |
-    +---------------+----------+---------------+--------------------------+
+        GET /api/0/jcline/my_repo/tags HTTP/1.1
+        Host: example.com
+        Accept: application/json
 
-    Sample response
-    ^^^^^^^^^^^^^^^
+    Sample response:
 
-    ::
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Vary: Accept
+        Content-Type: application/json
 
         {
           "total_tags": 2,
           "tags": ["tag1", "tag2"]
         }
 
+    :param repo: The name of the repository to fetch the tags for.
+    :type  repo: str
+    :param username: The username of the user who owns the fork of the repo.
+    :type  username: str
+
+    :query string pattern: Filters the starting letters of the tags
     '''
     pattern = flask.request.args.get('pattern', None)
     if pattern is not None and not pattern.endswith('*'):