You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2013/11/24 13:05:30 UTC
git commit: updated refs/heads/master to fb92263
Updated Branches:
refs/heads/master 5ae6ebc15 -> fb92263e8
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.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/fb92263e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/fb92263e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/fb92263e
Branch: refs/heads/master
Commit: fb92263e8bdf68de3c04322a8d17d1d5986e78b0
Parents: 5ae6ebc
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Nov 24 16:05:00 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sun Nov 24 16:05:00 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +-
share/doc/ext/http-api-descr.json | 79 ----------------
share/doc/ext/httpdomain.py | 20 +++--
share/doc/src/api/database/bulk-api.rst | 3 +
share/doc/src/api/database/changes.rst | 4 +-
share/doc/src/api/database/common.rst | 5 ++
share/doc/src/api/database/compact.rst | 4 +
share/doc/src/api/database/misc.rst | 5 ++
share/doc/src/api/database/security.rst | 2 +
share/doc/src/api/database/temp-views.rst | 1 +
share/doc/src/api/ddoc/common.rst | 10 +++
share/doc/src/api/ddoc/render.rst | 12 ++-
share/doc/src/api/ddoc/rewrites.rst | 7 +-
share/doc/src/api/ddoc/views.rst | 114 ++++++++++++------------
share/doc/src/api/document/attachments.rst | 4 +
share/doc/src/api/document/common.rst | 5 ++
share/doc/src/api/local.rst | 4 +
share/doc/src/api/server/authn.rst | 3 +
share/doc/src/api/server/common.rst | 12 +++
share/doc/src/api/server/configuration.rst | 5 ++
20 files changed, 153 insertions(+), 149 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index a6a5e76..f332e5c 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) \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/ext/http-api-descr.json
----------------------------------------------------------------------
diff --git a/share/doc/ext/http-api-descr.json b/share/doc/ext/http-api-descr.json
deleted file mode 100644
index e7672e4..0000000
--- 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
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index d5df2b7..5571054 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))
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index b274d84..d13ff30 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
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index ba99596..2036220 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
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index e3e3657..30c99d0 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.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index d2b90d7..cdafb26 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
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/database/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst
index 71d1fd9..7f0b484 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
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/database/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst
index 7bdf88e..3757133 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.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/database/temp-views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/temp-views.rst b/share/doc/src/api/database/temp-views.rst
index d9ac16d..2888e3a 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.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index af37e61..fb992f7 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
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/ddoc/render.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/render.rst b/share/doc/src/api/ddoc/render.rst
index 9c6b1c4..5f99dec 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.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/ddoc/rewrites.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/rewrites.rst b/share/doc/src/api/ddoc/rewrites.rst
index 4e9a9b5..90abddd 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
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index a456dab..5e56f9c 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": [
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
index 8514993..f2403aa 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
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index 0a1e28c..62775cf 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.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/local.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
index c91c96b..3615c2e 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
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/server/authn.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/authn.rst b/share/doc/src/api/server/authn.rst
index 2495e1e..076bfdb 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.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index 2c14fee..98bb19b 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.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fb92263e/share/doc/src/api/server/configuration.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/configuration.rst b/share/doc/src/api/server/configuration.rst
index 643b8ec..5f53002 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.