diff options
author | Alexander Shorin <kxepal@apache.org> | 2013-11-24 16:05:00 +0400 |
---|---|---|
committer | Alexander Shorin <kxepal@apache.org> | 2013-11-24 16:05:00 +0400 |
commit | fb92263e8bdf68de3c04322a8d17d1d5986e78b0 (patch) | |
tree | 880e961fc5417de1db0ddbd6f8ff832e727e875b | |
parent | 5ae6ebc157ea5d219bf382e1a59c6749708af982 (diff) | |
download | couchdb-fb92263e8bdf68de3c04322a8d17d1d5986e78b0.tar.gz |
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.
-rw-r--r-- | share/doc/build/Makefile.am | 3 | ||||
-rw-r--r-- | share/doc/ext/http-api-descr.json | 79 | ||||
-rw-r--r-- | share/doc/ext/httpdomain.py | 20 | ||||
-rw-r--r-- | share/doc/src/api/database/bulk-api.rst | 3 | ||||
-rw-r--r-- | share/doc/src/api/database/changes.rst | 4 | ||||
-rw-r--r-- | share/doc/src/api/database/common.rst | 5 | ||||
-rw-r--r-- | share/doc/src/api/database/compact.rst | 4 | ||||
-rw-r--r-- | share/doc/src/api/database/misc.rst | 5 | ||||
-rw-r--r-- | share/doc/src/api/database/security.rst | 2 | ||||
-rw-r--r-- | share/doc/src/api/database/temp-views.rst | 1 | ||||
-rw-r--r-- | share/doc/src/api/ddoc/common.rst | 10 | ||||
-rw-r--r-- | share/doc/src/api/ddoc/render.rst | 12 | ||||
-rw-r--r-- | share/doc/src/api/ddoc/rewrites.rst | 7 | ||||
-rw-r--r-- | share/doc/src/api/ddoc/views.rst | 114 | ||||
-rw-r--r-- | share/doc/src/api/document/attachments.rst | 4 | ||||
-rw-r--r-- | share/doc/src/api/document/common.rst | 5 | ||||
-rw-r--r-- | share/doc/src/api/local.rst | 4 | ||||
-rw-r--r-- | share/doc/src/api/server/authn.rst | 3 | ||||
-rw-r--r-- | share/doc/src/api/server/common.rst | 12 | ||||
-rw-r--r-- | share/doc/src/api/server/configuration.rst | 5 |
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. |