Provides short description for the HTTP API reference entries.

The description is defined within special JSON file instead of markup attributes.
There should be way to hack sphinx for this, but currently I don't know how to
do this. Hope this will be fixed in nearest future.

3 files changed, 89 insertions, 3 deletions

diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index d03eb30ab..5a9441fe9 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -414,7 +414,8 @@ src_files_html = \
 
 sphinx_extensions = \
     ../ext/github.py \
-    ../ext/httpdomain.py
+    ../ext/httpdomain.py \
+    ../ext/http-api-descr.json
 
 EXTRA_DIST = \
     $(image_files) \
diff --git a/share/doc/ext/http-api-descr.json b/share/doc/ext/http-api-descr.json
new file mode 100644
index 000000000..e7672e451
--- /dev/null
+++ b/share/doc/ext/http-api-descr.json
@@ -0,0 +1,79 @@
+{
+    "GET /": "Returns the welcome message and version information",
+    "GET /_active_tasks": "Obtains a list of the tasks running in the server",
+    "GET /_all_dbs": "Returns a list of all the databases",
+    "GET /_config": "Obtains a list of the entire server configuration",
+    "GET /_config/{section}": "Returns all the configuration values for the specified section",
+    "DELETE /_config/{section}/{key}": "Removes the current setting",
+    "GET /_config/{section}/{key}": "Returns a specific section/configuration value",
+    "PUT /_config/{section}/{key}": "Sets the specified configuration value",
+    "GET /_db_updates": "Return the server changes of databases",
+    "GET /_log": "Returns the server log file",
+    "POST /_replicate": "Starts or cancels the replication",
+    "POST /_restart": "Restarts the server",
+    "DELETE /_session": "Logout Cookie-based user",
+    "GET /_session": "Returns Cookie-based login user information",
+    "POST /_session": "Authenticates user by Cookie-based user login",
+    "GET /_stats": "Returns server statistics",
+    "GET /_utils/": "CouchDB administration interface (Futon)",
+    "GET /_uuids": "Generates a list of UUIDs from the server",
+    "GET /favicon.ico": "Returns the site icon",
+    "DELETE /{db}": "Deletes an existing database",
+    "GET /{db}": "Returns the database information",
+    "HEAD /{db}": "Checks the database existence",
+    "POST /{db}": "Creates a new document with generic ID if he had not specified",
+    "PUT /{db}": "Creates a new database",
+    "GET /{db}/_all_docs": "Returns a built-in view of all documents in this database",
+    "POST /{db}/_all_docs": "Returns certain rows from the built-in view of all documents",
+    "POST /{db}/_bulk_docs": "Inserts or updates multiple documents in to the database in a single request",
+    "GET /{db}/_changes": "Returns changes for the given database",
+    "POST /{db}/_changes": "Returns changes for the given database for certain document IDs",
+    "POST /{db}/_compact": "Starts a compaction for the database",
+    "POST /{db}/_compact/{ddoc}": "Starts a compaction for all the views in the selected design document",
+    "COPY /{db}/_design/{ddoc}": "Copies the design document",
+    "DELETE /{db}/_design/{ddoc}": "Deletes the design document",
+    "GET /{db}/_design/{ddoc}": "Returns the design document",
+    "HEAD /{db}/_design/{ddoc}": "Returns bare information in the HTTP Headers for the design document",
+    "PUT /{db}/_design/{ddoc}": "Creates a new design document, or new version of an existing one",
+    "GET /{db}/_design/{ddoc}/_info": "Returns view index information for the specified design document",
+    "GET /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}": "Executes a list function against the view from other design document",
+    "POST /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}": "",
+    "GET /{db}/_design/{ddoc}/_list/{func}/{view}": "Executes a list function against the view from the same design document",
+    "POST /{db}/_design/{ddoc}/_list/{func}/{view}": "",
+    "ANY /{db}/_design/{ddoc}/_rewrite/{path}": "Rewrites HTTP request for the specified path by using stored routing rules",
+    "GET /{db}/_design/{ddoc}/_show/{func}": "Executes a show function against null document",
+    "POST /{db}/_design/{ddoc}/_show/{func}": "",
+    "GET /{db}/_design/{ddoc}/_show/{func}/{docid}": "Executes a show function against the specified document",
+    "POST /{db}/_design/{ddoc}/_show/{func}/{docid}": "",
+    "POST /{db}/_design/{ddoc}/_update/{func}": "Executes an update function",
+    "PUT /{db}/_design/{ddoc}/_update/{func}/{docid}": "Executes an update function against the specified document",
+    "GET /{db}/_design/{ddoc}/_view/{view}": "Returns results for the specified stored view",
+    "POST /{db}/_design/{ddoc}/_view/{view}": "Returns certain rows for the specified stored view",
+    "DELETE /{db}/_design/{ddoc}/{attname}": "Deletes an attachment of a design document",
+    "GET /{db}/_design/{ddoc}/{attname}": "Gets the attachment of a design document",
+    "HEAD /{db}/_design/{ddoc}/{attname}": "Returns bare information in the HTTP Headers for the attachment",
+    "PUT /{db}/_design/{ddoc}/{attname}": "Adds an attachment of a design document",
+    "POST /{db}/_ensure_full_commit": "Makes sure all uncommitted changes are written and synchronized to the disk",
+    "COPY /{db}/_local/{docid}": "Copies the non-replicated document",
+    "DELETE /{db}/_local/{docid}": "Deletes the non-replicated document",
+    "GET /{db}/_local/{docid}": "Returns the latest revision of the non-replicated document",
+    "PUT /{db}/_local/{docid}": "Inserts a new version of the non-replicated document",
+    "POST /{db}/_missing_revs": "By given list of document revisions, returns the document revisions that do not exist in the database",
+    "POST /{db}/_purge": "Purges some historical documents entirely from database history",
+    "POST /{db}/_revs_diff": "By given list of document revisions, returns differences between the given revisions and ones that are in the database",
+    "GET /{db}/_revs_limit": "Returns the limit of historical revisions to store for a single document in the database",
+    "PUT /{db}/_revs_limit": "Sets the limit of historical revisions to store for a single document in the database",
+    "GET /{db}/_security": "Returns the special security object for the database",
+    "PUT /{db}/_security": "Sets the special security object for the database",
+    "POST /{db}/_temp_view": "Executes a given view function for all documents and returns the result",
+    "POST /{db}/_view_cleanup": "Removes view files that are not used by any design document",
+    "COPY /{db}/{docid}": "Copies the document",
+    "DELETE /{db}/{docid}": "Deletes the document",
+    "GET /{db}/{docid}": "Returns the document",
+    "HEAD /{db}/{docid}": "Returns bare information in the HTTP Headers for the document",
+    "PUT /{db}/{docid}": "Creates a new document, or new version of an existing document",
+    "DELETE /{db}/{docid}/{attname}": "Deletes an attachment of a document",
+    "GET /{db}/{docid}/{attname}": "Gets the attachment of a document",
+    "HEAD /{db}/{docid}/{attname}": "Returns bare information in the HTTP Headers for the attachment",
+    "PUT /{db}/{docid}/{attname}": "Adds an attachment of a document"
+}
\ No newline at end of file
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index a2de686bb..afc81b564 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -9,6 +9,8 @@
 
 """
 
+import os
+import json
 import re
 
 from docutils import nodes
@@ -452,6 +454,8 @@ class HTTPIndex(Index):
     name = 'api'
     localname = 'HTTP API Reference'
     shortname = 'API Reference'
+    api_descr = json.load(open(os.path.join(os.path.dirname(__file__),
+                                            'http-api-descr.json')))
 
     def generate(self, docnames=None):
         content = {}
@@ -461,9 +465,11 @@ class HTTPIndex(Index):
         items = sorted(items, key=lambda item: item[1])
         for method, path, info in items:
             entries = content.setdefault(path, [])
+            entry_name = method.upper() + ' ' + path
             entries.append([
-                method.upper() + ' ' + path, 0, info[0],
-                http_resource_anchor(method, path), '', '', info[1]
+                entry_name, 0, info[0],
+                http_resource_anchor(method, path),
+                '', '', self.api_descr.get(entry_name, '')
             ])
         items = sorted(
             (path, sort_by_method(entries))