Docs: add synopsis, deprecated and noindex options to HTTP endpoints

Synopsis is the short description of the HTTP endpoint that used in
the generated API reference.

Deprecated option, if specified, adds special remark to the endpoint
description in the same reference.

Noindex excludes endpoint from the reference.

The old source of synopsises is removed.

20 files changed, 153 insertions, 149 deletions

diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index a6a5e76dc..f332e5c55 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -454,8 +454,7 @@ src_files_html = \
 sphinx_extensions = \
     ../ext/configdomain.py \
     ../ext/github.py \
-    ../ext/httpdomain.py \
-    ../ext/http-api-descr.json
+    ../ext/httpdomain.py
 
 EXTRA_DIST = \
     $(image_files) \
diff --git a/share/doc/ext/http-api-descr.json b/share/doc/ext/http-api-descr.json
deleted file mode 100644
index e7672e451..000000000
--- a/share/doc/ext/http-api-descr.json
+++ /dev/null
@@ -1,79 +0,0 @@
-{
-    "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 d5df2b75c..5571054f2 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -9,8 +9,6 @@
 
 """
 
-import os
-import json
 import re
 
 from docutils import nodes
@@ -24,7 +22,7 @@ from pygments.util import ClassNotFound
 from sphinx import addnodes
 from sphinx.roles import XRefRole
 from sphinx.domains import Domain, ObjType, Index
-from sphinx.directives import ObjectDescription
+from sphinx.directives import ObjectDescription, directives
 from sphinx.util.nodes import make_refnode
 from sphinx.util.docfields import GroupedField, TypedField
 
@@ -260,6 +258,12 @@ class HTTPResource(ObjectDescription):
                      names=('statuscode', 'status', 'code'))
     ]
 
+    option_spec = {
+        'deprecated': directives.flag,
+        'noindex': directives.flag,
+        'synopsis': lambda x: x,
+    }
+
     method = NotImplemented
 
     def handle_signature(self, sig, signode):
@@ -295,7 +299,11 @@ class HTTPResource(ObjectDescription):
 
     def add_target_and_index(self, name_cls, sig, signode):
         signode['ids'].append(http_resource_anchor(*name_cls[1:]))
-        self.env.domaindata['http'][self.method][sig] = (self.env.docname, '')
+        if 'noindex' not in self.options:
+            self.env.domaindata['http'][self.method][sig] = (
+                self.env.docname,
+                self.options.get('synopsis', ''),
+                'deprecated' in self.options)
 
     def get_index_text(self, modname, name):
         return ''
@@ -454,8 +462,6 @@ 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 = {}
@@ -469,7 +475,7 @@ class HTTPIndex(Index):
             entries.append([
                 entry_name, 0, info[0],
                 http_resource_anchor(method, path),
-                '', '', self.api_descr.get(entry_name, '')
+                '', 'Deprecated' if info[2] else '', info[1]
             ])
         items = sorted(
             (path, sort_by_method(entries))
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index b274d847e..d13ff3034 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -17,6 +17,7 @@
 =================
 
 .. http:get:: /{db}/_all_docs
+  :synopsis: Returns a built-in view of all documents in this database
 
   Returns a JSON structure of all of the documents in a given database.
   The information is returned as a JSON structure containing meta
@@ -134,6 +135,7 @@
 
 
 .. http:post:: /{db}/_all_docs
+  :synopsis: Returns certain rows from the built-in view of all documents
 
   The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
   selected from the database. This enables you to request multiple
@@ -191,6 +193,7 @@
 ==================
 
 .. http:post:: /{db}/_bulk_docs
+  :synopsis: Inserts or updates multiple documents in to the database in a single request
 
   The bulk document API allows you to create and update multiple documents
   at the same time within a single request. The basic operation is similar
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index ba99596c7..203622076 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -18,6 +18,7 @@
 ================
 
 .. http:get:: /{db}/_changes
+  :synopsis: Returns changes for the given database
 
   Returns a sorted list of changes made to documents in the database, in time
   order of application, can be obtained from the database's ``_changes``
@@ -48,7 +49,7 @@
   :query string feed: see :ref:`changes`. Default is ``normal``.
   :query string filter: Reference to a :ref:`filter function <filterfun>`
     from a design document that will filter whole stream emitting only filtered
-    events. See the section `Change Notifications in the book 
+    events. See the section `Change Notifications in the book
     CouchDB The Definitive Guide`_ for more information.
   :query number heartbeat: Period in *milliseconds* after which an empty line is
     sent in the results. Only applicable for :ref:`longpoll <changes/longpoll>`
@@ -164,6 +165,7 @@
 
 
 .. http:post:: /{db}/_changes
+  :synopsis: Returns changes for the given database for certain document IDs
 
   Requests the database changes feed in the same way as
   :get:`/{db}/_changes` does, but is widely used with
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index e3e365780..30c99d074 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -16,6 +16,7 @@
 =======
 
 .. http:head:: /{db}
+  :synopsis: Checks the database existence
 
   Returns the HTTP Headers containing a minimal amount of information
   about the specified database. Since the response body is empty, using the
@@ -45,6 +46,7 @@
 
 
 .. http:get:: /{db}
+  :synopsis: Returns the database information
 
   Gets information about the specified database.
 
@@ -105,6 +107,7 @@
 
 
 .. http:put:: /{db}
+  :synopsis: Creates a new database
 
   Creates a new database. The database name ``{db}`` must be composed by
   following next rules:
@@ -214,6 +217,7 @@
 
 
 .. http:delete:: /{db}
+  :synopsis: Deletes an existing database
 
   Deletes the specified database, and all the documents and attachments
   contained within it.
@@ -254,6 +258,7 @@
 
 
 .. http:post:: /{db}
+  :synopsis: Creates a new document with generic ID if he had not specified
 
   Creates a new document in the specified database, using the supplied JSON
   document structure.
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index d2b90d713..cdafb2607 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -17,6 +17,7 @@
 ================
 
 .. http:post:: /{db}/_compact
+  :synopsis: Starts a compaction for the database
 
   Request compaction of the specified database. Compaction compresses the
   disk database file by performing the following operations:
@@ -86,6 +87,7 @@
 ===========================
 
 .. http:post:: /{db}/_compact/{ddoc}
+  :synopsis: Starts a compaction for all the views in the selected design document
 
   Compacts the view indexes associated with the specified design document.
   If may be that compacting a large view can return more storage than
@@ -143,6 +145,7 @@
 ===========================
 
 .. http:post:: /{db}/_ensure_full_commit
+  :synopsis: Makes sure all uncommitted changes are written and synchronized to the disk
 
   Commits any recent changes to the specified database to disk. You should
   call this if you want to ensure that recent changes have been flushed.
@@ -196,6 +199,7 @@
 =====================
 
 .. http:post:: /{db}/_view_cleanup
+  :synopsis: Removes view files that are not used by any design document
 
   Removes view index files that are no longer required by CouchDB as a result
   of changed views within design documents. As the view filename is based on
diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst
index 71d1fd9fd..7f0b484f4 100644
--- a/share/doc/src/api/database/misc.rst
+++ b/share/doc/src/api/database/misc.rst
@@ -17,6 +17,7 @@
 ==============
 
 .. http:post:: /{db}/_purge
+  :synopsis: Purges some historical documents entirely from database history
 
   A database purge permanently removes the references to deleted documents
   from the database. Normal deletion of a document within CouchDB does not
@@ -129,6 +130,7 @@ database must be examined.
 =====================
 
 .. http:post:: /{db}/_missing_revs
+  :synopsis: By given list of document revisions returns the document revisions that do not exist in the database
 
   With given a list of document revisions, returns the document revisions that
   do not exist in the database.
@@ -187,6 +189,7 @@ database must be examined.
 ==================
 
 .. http:post:: /{db}/_revs_diff
+  :synopsis: By given list of document revisions returns differences between the given revisions and ones that are in the database
 
   Given a set of document/revision IDs, returns the subset of those that do
   not correspond to revisions stored in the database.
@@ -269,6 +272,7 @@ database must be examined.
 ===================
 
 .. http:get:: /{db}/_revs_limit
+  :synopsis: Returns the limit of historical revisions to store for a single document in the database
 
   Gets the current ``revs_limit`` (revision limit) setting.
 
@@ -302,6 +306,7 @@ database must be examined.
 
 
 .. http:put:: /{db}/_revs_limit
+  :synopsis: Sets the limit of historical revisions to store for a single document in the database
 
   Sets the maximum number of document revisions that will be tracked by
   CouchDB, even after compaction has occurred. You can set the revision
diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst
index 7bdf88e1b..37571333d 100644
--- a/share/doc/src/api/database/security.rst
+++ b/share/doc/src/api/database/security.rst
@@ -17,6 +17,7 @@
 =================
 
 .. http:get:: /{db}/_security
+  :synopsis: Returns the special security object for the database
 
   Returns the current security object from the specified database.
 
@@ -117,6 +118,7 @@
 
 
 .. http:put:: /{db}/_security
+  :synopsis: Sets the special security object for the database
 
   Sets the security object for the given database.
 
diff --git a/share/doc/src/api/database/temp-views.rst b/share/doc/src/api/database/temp-views.rst
index d9ac16df0..2888e3a8f 100644
--- a/share/doc/src/api/database/temp-views.rst
+++ b/share/doc/src/api/database/temp-views.rst
@@ -17,6 +17,7 @@
 ==================
 
 .. http:post:: /{db}/_temp_view
+  :synopsis: Executes a given view function for all documents and returns the result
 
   Creates (and executes) a temporary view based on the view function
   supplied in the JSON request.
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index af37e61f9..fb992f710 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -17,6 +17,7 @@
 ==========================
 
 .. http:head:: /{db}/_design/{ddoc}
+  :synopsis: Returns bare information in the HTTP Headers for the design document
 
   Returns the HTTP Headers containing a minimal amount of information
   about the specified design document.
@@ -27,6 +28,7 @@
 
 
 .. http:get:: /{db}/_design/{ddoc}
+  :synopsis: Returns the design document
 
   Returns design document with the specified design document` from the specified
   database. Unless you request a specific revision, the latest revision of the
@@ -38,6 +40,7 @@
 
 
 .. http:put:: /{db}/_design/{ddoc}
+  :synopsis: Creates a new design document or new version of an existing one
 
   The :method:`PUT` method creates a new named design document, or creates
   a new revision of the existing design document.
@@ -68,6 +71,7 @@
 
 
 .. http:delete:: /{db}/_design/{ddoc}
+  :synopsis: Deletes the design document
 
   Deletes the specified document from the database. You must supply the
   current (latest) revision, either by using the ``rev`` parameter to
@@ -78,6 +82,7 @@
     :delete:`/{db}/{docid}`
 
 .. http:copy:: /{db}/_design/{ddoc}
+  :synopsis: Copies the design document
 
   The :method:`COPY` (which is non-standard HTTP) copies an existing
   design document to a new or existing one.
@@ -98,6 +103,7 @@
 =====================================
 
 .. http:head:: /{db}/_design/{ddoc}/{attname}
+  :synopsis: Returns bare information in the HTTP Headers for the attachment
 
   Returns the HTTP headers containing a minimal amount of information
   about the specified attachment.
@@ -107,6 +113,7 @@
     :head:`/{db}/{docid}/{attname}`
 
 .. http:get:: /{db}/_design/{ddoc}/{attname}
+  :synopsis: Gets the attachment of a design document
 
   Returns the file attachment associated with the design document.
   The raw data of the associated attachment is returned (just as if you were
@@ -117,6 +124,7 @@
     :get:`/{db}/{docid}/{attname}`
 
 .. http:put:: /{db}/_design/{ddoc}/{attname}
+  :synopsis: Adds an attachment of a design document
 
   Uploads the supplied content as an attachment to the specified design
   document. The attachment name provided must be a URL encoded string.
@@ -126,6 +134,7 @@
     :put:`/{db}/{docid}/{attname}`
 
 .. http:delete:: /{db}/_design/{ddoc}/{attname}
+  :synopsis: Deletes an attachment of a design document
 
   Deletes the attachment of the specified design document.
 
@@ -140,6 +149,7 @@
 ================================
 
 .. http:get:: /{db}/_design/{ddoc}/_info
+  :synopsis: Returns view index information for the specified design document
 
   Obtains information about the specified design document, including the index,
   index size and current status of the design document and associated
diff --git a/share/doc/src/api/ddoc/render.rst b/share/doc/src/api/ddoc/render.rst
index 9c6b1c4d5..5f99decce 100644
--- a/share/doc/src/api/ddoc/render.rst
+++ b/share/doc/src/api/ddoc/render.rst
@@ -17,7 +17,10 @@
 ==========================================
 
 .. http:get:: /{db}/_design/{ddoc}/_show/{func}
+  :synopsis: Executes a show function against null document
+
 .. http:post:: /{db}/_design/{ddoc}/_show/{func}
+  :synopsis: Same as GET /{db}/_design/{ddoc}/_show/{func}
 
   Applies :ref:`show function <showfun>` for `null` document.
 
@@ -74,7 +77,9 @@
 =================================================
 
 .. http:get:: /{db}/_design/{ddoc}/_show/{func}/{docid}
+  :synopsis: Executes a show function against the specified document
 .. http:post:: /{db}/_design/{ddoc}/_show/{func}/{docid}
+  :synopsis: Same as GET /{db}/_design/{ddoc}/_show/{func}/{docid}
 
   Applies :ref:`show function <showfun>` for the specified document.
 
@@ -132,7 +137,9 @@
 ====================================================
 
 .. http:get:: /{db}/_design/{ddoc}/_list/{func}/{view}
+  :synopsis: Executes a list function against the view from the same design document
 .. http:post:: /{db}/_design/{ddoc}/_list/{func}/{view}
+  :synopsis: Same as GET /{db}/_design/{ddoc}/_list/{func}/{view}
 
   Applies :ref:`list function <listfun>` for the :ref:`view function <viewfun>`
   from the same design document.
@@ -194,7 +201,9 @@
 ===============================================================
 
 .. http:get:: /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
+  :synopsis: Executes a list function against the view from other design document
 .. http:post:: /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
+  :synopsis: Same as GET /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
 
   Applies :ref:`list function <listfun>` for the :ref:`view function <viewfun>`
   from the other design document.
@@ -257,6 +266,7 @@
 ==============================================
 
 .. http:post:: /{db}/_design/{ddoc}/_update/{func}
+  :synopsis: Executes an update function against the null document
 
   Executes :ref:`update function <updatefun>` on server side for ``null``
   document.
@@ -320,7 +330,7 @@
 =====================================================
 
 .. http:put:: /{db}/_design/{ddoc}/_update/{func}/{docid}
-
+  :synopsis: Executes an update function against the specified document
 
   Executes :ref:`update function <updatefun>` on server side for the specified
   document.
diff --git a/share/doc/src/api/ddoc/rewrites.rst b/share/doc/src/api/ddoc/rewrites.rst
index 4e9a9b53f..90abddd5e 100644
--- a/share/doc/src/api/ddoc/rewrites.rst
+++ b/share/doc/src/api/ddoc/rewrites.rst
@@ -17,6 +17,7 @@
 ========================================
 
 .. http:any:: /{db}/_design/{ddoc}/_rewrite/{path}
+  :synopsis: Rewrites HTTP request for the specified path by using stored routing rules
 
   Rewrites the specified path by rules defined in the specified design document.
 
@@ -58,9 +59,9 @@
   fields. The identified token are matched to the rule and will replace var.
   If ``'*'`` is found in the rule it will contain the remaining part if it
   exists.
-  
+
   Examples:
-  
+
   +--------------------------------------+----------+------------------+-------+
   |               Rule                   |    Url   |  Rewrite to      | Tokens|
   +======================================+==========+==================+=======+
@@ -82,7 +83,7 @@
   +--------------------------------------+----------+------------------+-------+
 
   Request method, header, query parameters, request payload and response body
-  are depended on endpoint to which url will be rewrited.
+  are depended on endpoint to which url will be rewritten.
 
   :param db: Database name
   :param ddoc: Design document name
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index a456daba2..5e56f9c64 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -17,6 +17,7 @@
 ==========================================
 
 .. http:get:: /{db}/_design/{ddoc}/_view/{view}
+  :synopsis: Returns results for the specified stored view
 
   Executes the specified view function from the specified design document.
 
@@ -124,6 +125,7 @@
 
 
 .. http:post:: /{db}/_design/{ddoc}/_view/{view}
+  :synopsis: Returns certain rows for the specified stored view
 
   Executes the specified view function from the specified design document.
   Unlike :get:`/{db}/_design/{ddoc}/_view/{view}` for accessing views, the
@@ -341,107 +343,107 @@ content. The basic order of output is as follows:
   ETag: "8LA1LZPQ37B6R9U8BK9BGQH27"
   Server: CouchDB (Erlang/OTP)
   Transfer-Encoding: chunked
-  
+
   {
-      "offset": 0, 
+      "offset": 0,
       "rows": [
           {
-              "id": "dummy-doc", 
-              "key": null, 
+              "id": "dummy-doc",
+              "key": null,
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": false, 
+              "id": "dummy-doc",
+              "key": false,
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": true, 
+              "id": "dummy-doc",
+              "key": true,
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": 0, 
+              "id": "dummy-doc",
+              "key": 0,
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": 1, 
+              "id": "dummy-doc",
+              "key": 1,
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": 10, 
+              "id": "dummy-doc",
+              "key": 10,
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": 42, 
+              "id": "dummy-doc",
+              "key": 42,
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": "10", 
+              "id": "dummy-doc",
+              "key": "10",
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": "hello", 
+              "id": "dummy-doc",
+              "key": "hello",
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": "Hello", 
+              "id": "dummy-doc",
+              "key": "Hello",
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
+              "id": "dummy-doc",
               "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": [], 
+              "id": "dummy-doc",
+              "key": [],
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
+              "id": "dummy-doc",
               "key": [
-                  1, 
-                  2, 
+                  1,
+                  2,
                   3
-              ], 
+              ],
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
+              "id": "dummy-doc",
               "key": [
-                  2, 
+                  2,
                   3
-              ], 
+              ],
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
+              "id": "dummy-doc",
               "key": [
                   3
-              ], 
+              ],
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
-              "key": {}, 
+              "id": "dummy-doc",
+              "key": {},
               "value": null
-          }, 
+          },
           {
-              "id": "dummy-doc", 
+              "id": "dummy-doc",
               "key": {
                   "foo": "bar"
-              }, 
+              },
               "value": null
           }
-      ], 
+      ],
       "total_rows": 17
   }
 
@@ -469,7 +471,7 @@ You can reverse the order of the returned view information by using the
   ETag: "Z4N468R15JBT98OM0AMNSR8U"
   Server: CouchDB (Erlang/OTP)
   Transfer-Encoding: chunked
-  
+
   {
       "offset": 0,
       "rows": [
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
index 8514993ba..f2403aa17 100644
--- a/share/doc/src/api/document/attachments.rst
+++ b/share/doc/src/api/document/attachments.rst
@@ -17,6 +17,7 @@
 ======================
 
 .. http:head:: /{db}/{docid}/{attname}
+  :synopsis: Returns bare information in the HTTP Headers for the attachment
 
   Returns the HTTP headers containing a minimal amount of information
   about the specified attachment. The method supports the same query
@@ -70,6 +71,7 @@
 
 
 .. http:get:: /{db}/{docid}/{attname}
+  :synopsis: Gets the attachment of a document
 
   Returns the file attachment associated with the document.
   The raw data of the associated attachment is returned (just as if you were
@@ -102,6 +104,7 @@
 
 
 .. http:put:: /{db}/{docid}/{attname}
+  :synopsis: Adds an attachment of a document
 
   Uploads the supplied content as an attachment to the specified document.
   The attachment name provided must be a URL encoded string. You must also
@@ -182,6 +185,7 @@
 
 
 .. http:delete:: /{db}/{docid}/{attname}
+  :synopsis: Deletes an attachment of a document
 
   Deletes the attachment ``attachment`` of the specified ``doc``. You must
   supply the ``rev`` query parameter or :header:`If-Match` with the current
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index 0a1e28c13..62775cf33 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -17,6 +17,7 @@
 ===========
 
 .. http:head:: /{db}/{docid}
+  :synopsis: Returns bare information in the HTTP Headers for the document
 
   Returns the HTTP Headers containing a minimal amount of information
   about the specified document. The method supports the same query
@@ -63,6 +64,7 @@
 
 
 .. http:get:: /{db}/{docid}
+  :synopsis: Returns the document
 
   Returns document by the specified ``docid`` from the specified ``db``.
   Unless you request a specific revision, the latest revision of the
@@ -165,6 +167,7 @@
     }
 
 .. http:put:: /{db}/{docid}
+  :synopsis: Creates a new document or new version of an existing document
 
   The :method:`PUT` method creates a new named document, or creates a new
   revision of the existing document. Unlike the :post:`/{db}`, you
@@ -237,6 +240,7 @@
 
 
 .. http:delete:: /{db}/{docid}
+  :synopsis: Deletes the document
 
   Deletes the specified document from the database. You must supply the
   current (latest) revision, either by using the ``rev`` parameter to
@@ -309,6 +313,7 @@
 
 
 .. http:copy:: /{db}/{docid}
+  :synopsis: Copies the document within the same database
 
   The :method:`COPY` (which is non-standard HTTP) copies an existing
   document to a new or existing document.
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
index c91c96b7f..3615c2eff 100644
--- a/share/doc/src/api/local.rst
+++ b/share/doc/src/api/local.rst
@@ -56,24 +56,28 @@ A list of the available methods and URL paths are provided below:
 ========================
 
 .. http:get:: /{db}/_local/{docid}
+  :synopsis: Returns the latest revision of the local document
 
   Gets the specified local document. The semantics are identical to
   accessing a standard document in the specified database, except that the
   document is not replicated. See :get:`/{db}/{docid}`.
 
 .. http:put:: /{db}/_local/{docid}
+  :synopsis: Inserts a new version of the local document
 
   Stores the specified local document. The semantics are identical to
   storing a standard document in the specified database, except that the
   document is not replicated. See :put:`/{db}/{docid}`.
 
 .. http:delete:: /{db}/_local/{docid}
+  :synopsis: Deletes the local document
 
   Deletes the specified local document. The semantics are identical to
   deleting a standard document in the specified database, except that the
   document is not replicated. See :delete:`/{db}/{docid}`.
 
 .. http:copy:: /{db}/_local/{docid}
+  :synopsis: Copies the local document within the same database
 
   Copies the specified local document. The semantics are identical to
   copying a standard document in the specified database, except that the
diff --git a/share/doc/src/api/server/authn.rst b/share/doc/src/api/server/authn.rst
index 2495e1e9a..076bfdb3c 100644
--- a/share/doc/src/api/server/authn.rst
+++ b/share/doc/src/api/server/authn.rst
@@ -88,6 +88,7 @@ To obtain the first token and thus authenticate a user for the first time, the
 -------------
 
 .. http:post:: /_session
+  :synopsis: Authenticates user by Cookie-based user login
 
   Initiates new session for specified user credentials by providing `Cookie`
   value.
@@ -178,6 +179,7 @@ To obtain the first token and thus authenticate a user for the first time, the
 
 
 .. http:get:: /_session
+  :synopsis: Returns Cookie-based login user information
 
   Returns complete information about authenticated user.
   This information contains :ref:`userctx_object`, authentication method and
@@ -230,6 +232,7 @@ To obtain the first token and thus authenticate a user for the first time, the
 
 
 .. http:delete:: /_session
+  :synopsis: Logout Cookie-based user
 
   Closes user's session.
 
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index 2c14fee3b..98bb19b56 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -17,6 +17,7 @@
 =====
 
 .. http:get:: /
+  :synopsis: Returns the welcome message and version information
 
   Accessing the root of a CouchDB instance returns meta information about
   the instance. The response is a JSON structure containing information
@@ -65,6 +66,7 @@
 ==================
 
 .. http:get:: /_active_tasks
+  :synopsis: Obtains a list of the tasks running in the server
 
   List of running tasks, including the task type, name, status
   and process ID. The result is a JSON array of the currently running tasks,
@@ -168,6 +170,7 @@
 =============
 
 .. http:get:: /_all_dbs
+  :synopsis: Returns a list of all the databases
 
   Returns a list of all the databases in the CouchDB instance.
 
@@ -213,6 +216,7 @@
 .. versionadded:: 1.4
 
 .. http:get:: /_db_updates
+  :synopsis: Return the server changes of databases
 
   Returns a list of all database events in the CouchDB instance.
 
@@ -269,6 +273,7 @@
 =========
 
 .. http:get:: /_log
+  :synopsis: Returns the server log file
 
   Gets the CouchDB log, equivalent to accessing the local log file of the
   corresponding CouchDB instance.
@@ -341,6 +346,7 @@ jumping to ``offset`` bytes towards the beginning of the file first:
 ===============
 
 .. http:post:: /_replicate
+  :synopsis: Starts or cancels the replication
 
   Request, configure, or stop, a replication operation.
 
@@ -664,6 +670,7 @@ a 404 error.
 =============
 
 .. http:post:: /_restart
+  :synopsis: Restarts the server
 
   Restarts the CouchDB instance. You must be authenticated as a user with
   administration privileges for this to work.
@@ -708,6 +715,7 @@ a 404 error.
 ===========
 
 .. http:get:: /_stats
+  :synopsis: Returns server statistics
 
   The ``_stats`` resource returns a JSON object containing the statistics
   for the running server. The object is structured with top-level sections
@@ -888,6 +896,7 @@ structure is as follows:
 ===========
 
 .. http:get:: /_utils
+  :synopsis: Redirects to /_utils/
 
   Accesses the built-in Futon administration interface for CouchDB.
 
@@ -895,6 +904,7 @@ structure is as follows:
   :code 301: Redirects to :get:`/_utils/`
 
 .. http:get:: /_utils/
+  :synopsis: CouchDB administration interface (Futon)
 
   :>header Content-Type: :mimetype:`text/html`
   :>header Last-Modified: Static files modification timestamp
@@ -907,6 +917,7 @@ structure is as follows:
 ===========
 
 .. http:get:: /_uuids
+  :synopsis: Generates a list of UUIDs from the server
 
   Requests one or more Universally Unique Identifiers (UUIDs) from the
   CouchDB instance. The response is a JSON object providing a list of
@@ -992,6 +1003,7 @@ You can verify the change by obtaining a list of UUIDs:
 ================
 
 .. http:get:: /favicon.ico
+  :synopsis: Returns the site icon
 
   Binary content for the `favicon.ico` site icon.
 
diff --git a/share/doc/src/api/server/configuration.rst b/share/doc/src/api/server/configuration.rst
index 643b8ecc2..5f5300243 100644
--- a/share/doc/src/api/server/configuration.rst
+++ b/share/doc/src/api/server/configuration.rst
@@ -23,6 +23,7 @@ the various configuration values within a running CouchDB instance.
 ============
 
 .. http:get:: /_config
+  :synopsis: Obtains a list of the entire server configuration
 
   Returns the entire CouchDB server configuration as a JSON structure. The
   structure is organized by different configuration sections, with
@@ -159,6 +160,7 @@ the various configuration values within a running CouchDB instance.
 ====================
 
 .. http:get:: /_config/{section}
+  :synopsis: Returns all the configuration values for the specified section
 
   Gets the configuration structure for a single section.
 
@@ -208,6 +210,7 @@ the various configuration values within a running CouchDB instance.
 ========================
 
 .. http:get:: /_config/{section}/{key}
+  :synopsis: Returns a specific section/configuration value
 
   Gets a single configuration value from within a specific configuration
   section.
@@ -250,6 +253,7 @@ the various configuration values within a running CouchDB instance.
 
 
 .. http:put:: /_config/{section}/{key}
+  :synopsis: Sets the specified configuration value
 
   Updates a configuration value. The new value should be supplied in the
   request body in the corresponding JSON format. If you are setting a string
@@ -295,6 +299,7 @@ the various configuration values within a running CouchDB instance.
 
 
 .. http:delete:: /_config/{section}/{key}
+  :synopsis: Removes the current setting
 
   Deletes a configuration value. The returned JSON will be the value of
   the configuration parameter before it was deleted.