couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kxe...@apache.org
Subject [46/50] git commit: updated refs/heads/1781-reorganize-and-improve-docs to 360107b
Date Wed, 21 Aug 2013 16:38:13 GMT
Update base DDoc API referece.


Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/a436f83c
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/a436f83c
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/a436f83c

Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: a436f83ce5cc674d89ea3b0b9fea2084766a180b
Parents: 32919fe
Author: Alexander Shorin <kxepal@apache.org>
Authored: Wed Aug 21 15:21:40 2013 +0400
Committer: Alexander Shorin <kxepal@apache.org>
Committed: Wed Aug 21 20:29:41 2013 +0400

----------------------------------------------------------------------
 share/doc/src/api/ddoc/common.rst    | 524 ++++++++----------------------
 share/doc/src/query-server/index.rst |   1 +
 2 files changed, 139 insertions(+), 386 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb/blob/a436f83c/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 c5ba9ce..0d6ec17 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -11,454 +11,206 @@
 .. the License.
 
 
-.. _api/ddoc.get:
+.. _api/ddoc:
 
-``GET /db/_design/design-doc``
-==============================
+``/db/_design/design-doc``
+==========================
 
-* **Method**: ``GET /db/_design/design-doc``
-* **Request**:  None
-* **Response**:  JSON of the existing design document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+.. http:head:: /{db}/_design/{ddocname}
 
-  * **Argument**: rev
+  Returns the HTTP Headers containing a minimal amount of information
+  about the specified design document.
 
-    * **Description**:  Specify the revision to return
-    * **Optional**: yes
-    * **Type**: string
+  .. seealso::
 
-  * **Argument**: revs
+    :http:head:`/{db}/{docid}`
 
-    * **Description**:  Return a list of the revisions for the document
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Supported Values**:
 
-        * **true**: Includes the revisions
+.. http:get:: /{db}/_design/{ddocname}
 
-  * **Argument**: revs_info
+  Returns design document with the specified design document` from the specified
+  database. Unless you request a specific revision, the latest revision of the
+  document will always be returned.
 
-    * **Description**:  Return a list of detailed revision information for the
-      document
-    * **Optional**: yes
-    * **Type**: boolean
-    * **Supported Values**:
+  .. seealso::
 
-      * **true**: Includes the revisions
+    :http:get:`/{db}/{docid}`
 
-Returns the specified design document, ``design-doc`` from the specified
-``db``. For example, to retrieve the design document ``recipes`` you
-would send the following request:
 
-.. code-block:: http
+.. http:put:: /{db}/_design/{ddocname}
 
-    GET http://couchdb:5984/recipes/_design/recipes
-    Content-Type: application/json
-
-The returned string will be the JSON of the design document:
-
-.. code-block:: javascript
-
-    {
-       "_id" : "_design/recipes",
-       "_rev" : "5-39f56a392b86bbee57e2138921346406"
-       "language" : "javascript",
-       "views" : {
-          "by_recipe" : {
-             "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }"
-          },
-       },
-    }
-
-A list of the revisions can be obtained by using the ``revs`` query
-argument, or an extended list of revisions using the ``revs_info`` query
-argument. This operates in the same way as for other documents. Fur
-further examples, see :http:get:`/{db}/{docid}`.
-
-.. _api/ddoc.put:
-
-``PUT /db/_design/design-doc``
-==============================
-
-* **Method**: ``PUT /db/_design/design-doc``
-* **Request**:  JSON of the design document
-* **Response**:  JSON status
-* **Admin Privileges Required**: no
-
-Upload the specified design document, ``design-doc``, to the specified
-database. The design document should follow the definition of a design
-document, as summarised in the following table.
-
-* **_id**:  Design Document ID
-* **_rev**:  Design Document Revision
-* **views**:  View
-
-  * **viewname**:  View Definition
-
-    * **map**:  Map Function for View
-    * **reduce (optional)**:  Reduce Function for View
-
-For more information on writing views, see :ref:`api/ddoc/view`.
-
-.. _api/ddoc.delete:
-
-``DELETE /db/_design/design-doc``
-=================================
-
-* **Method**: ``DELETE /db/_design/design-doc``
-* **Request**:  None
-* **Response**:  JSON of deleted design document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: rev
-
-    * **Description**:  Current revision of the document for validation
-    * **Optional**: yes
-    * **Type**: string
-
-* **HTTP Headers**
-
-  * **Header**: ``If-Match``
-
-    * **Description**: Current revision of the document for validation
-    * **Optional**: yes
-
-* **Return Codes**:
-
-  * **409**:
-    Supplied revision is incorrect or missing
-
-Delete an existing design document. Deleting a design document also
-deletes all of the associated view indexes, and recovers the
-corresponding space on disk for the indexes in question.
-
-To delete, you must specify the current revision of the design document
-using the ``rev`` query argument.
-
-For example:
-
-.. code-block:: http
-
-    DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8
-    Content-Type: application/json
-
-The response contains the delete document ID and revision:
-
-.. code-block:: javascript
-
-    {
-       "id" : "recipe/_design/recipes"
-       "ok" : true,
-       "rev" : "3-7a05370bff53186cb5d403f861aca154",
-    }
-
-.. _api/ddoc.copy:
-
-``COPY /db/_design/design-doc``
-===============================
-
-* **Method**: ``COPY /db/_design/design-doc``
-* **Request**: None
-* **Response**: JSON of the new document and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: rev
-
-    * **Description**:  Revision to copy from
-    * **Optional**: yes
-    * **Type**: string
-
-* **HTTP Headers**
-
-  * **Header**: ``Destination``
-
-    * **Description**: Destination document (and optional revision)
-    * **Optional**: no
-
-The ``COPY`` command (non-standard HTTP) copies an existing design
-document to a new or existing document.
-
-The source design document is specified on the request line, with the
-``Destination`` HTTP Header of the request specifying the target
-document.
+  The :http:method:`PUT` method creates a new named design document, or creates
+  a new revision of the existing design document.
 
-Copying a Design Document
--------------------------
+  The design documents have some agreement upon their fields and structure.
+  Currently it is the next:
 
-To copy the latest version of a design document to a new document you
-specify the base document and target document:
+  * **language** (*string*): Defines :ref:`Query Server <query-server>`
+    :ref:`key <config/query_servers>` to process design document functions
+  * **options** (*object*): View's default options
+  * **filters** (*object*): :ref:`Filter functions <filterfun>` definition
+  * **lists** (*object*): :ref:`List functions <listfun>` definition
+  * **rewrites** (*array*): Rewrite rules definition
+  * **shows** (*object*): :ref:`Show functions <showfun>` definition
+  * **updates** (*object*): :ref:`Update functions <updatefun>` definition
+  * **validate_doc_update** (*string*): :ref:`Validate document update <vdufun>`
+    function source
+  * **views** (*object*): :ref:`View functions <viewfun>` definition.
 
-.. code-block:: http
+  Note, that for ``filters``, ``lists``, ``shows`` and ``updates`` fields
+  objects are mapping of function name to string function source code.
+  For ``views`` mapping is the same except that values are objects with ``map``
+  and ``reduce`` (optional) keys which also contains functions source code.
 
-    COPY http://couchdb:5984/recipes/_design/recipes
-    Content-Type: application/json
-    Destination: /recipes/_design/recipelist
-
-The above request copies the design document ``recipes`` to the new
-design document ``recipelist``. The response is the ID and revision of
-the new document.
-
-.. code-block:: javascript
-
-    {
-       "id" : "recipes/_design/recipelist"
-       "rev" : "1-9c65296036141e575d32ba9c034dd3ee",
-    }
+  .. seealso::
 
-.. note::
-   Copying a design document does automatically reconstruct the view
-   indexes. These will be recreated, as with other views, the first
-   time the new view is accessed.
+    :http:put:`/{db}/{docid}`
 
-Copying from a Specific Revision
---------------------------------
 
-To copy *from* a specific version, use the ``rev`` argument to the query
-string:
+.. http:delete:: /{db}/_design/{ddocname}
 
-.. code-block:: http
+  Deletes the specified document from the database. You must supply the
+  current (latest) revision, either by using the ``rev`` parameter to
+  specify the revision.
 
-    COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5
-    Content-Type: application/json
-    Destination: recipes/_design/recipelist
-
-The new design document will be created using the specified revision of
-the source document.
+  .. seealso::
 
-Copying to an Existing Design Document
---------------------------------------
+    :http:delete:`/{db}/{docid}`
 
-To copy to an existing document, you must specify the current revision
-string for the target document, using the ``rev`` parameter to the
-``Destination`` HTTP Header string. For example:
+.. http:copy:: /{db}/_design/{ddocname}
 
-.. code-block:: http
+  The :http:method:`COPY` (which is non-standard HTTP) copies an existing
+  design document to a new or existing one.
 
-    COPY http://couchdb:5984/recipes/_design/recipes
-    Content-Type: application/json
-    Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee
+  .. note::
+     Copying a design document does automatically reconstruct the view
+     indexes. These will be recreated, as with other views, the first
+     time the new view is accessed.
 
-The return value will be the new revision of the copied document:
+  .. seealso::
 
-.. code-block:: javascript
+    :http:copy:`/{db}/{docid}`
 
-    {
-       "id" : "recipes/_design/recipes"
-       "rev" : "2-55b6a1b251902a2c249b667dab1c6692",
-    }
 
 .. _api/ddoc/attachment:
-.. _api/ddoc/attachment.get:
-
-``GET /db/_design/design-doc/attachment``
-=========================================
-
-* **Method**: ``GET /db/_design/design-doc/attachment``
-* **Request**: None
-* **Response**: Returns the attachment data
-* **Admin Privileges Required**: no
-
-Returns the file attachment ``attachment`` associated with the design
-document ``/_design_/design-doc``. The raw data of the associated
-attachment is returned (just as if you were accessing a static file. The
-returned HTTP ``Content-type`` will be the same as the content type set
-when the document attachment was submitted into the database.
-
-.. _api/ddoc/attachment.put:
-
-``PUT /db/_design/design-doc/attachment``
-=========================================
-
-* **Method**: ``PUT /db/_design/design-doc/attachment``
-* **Request**: Raw document data
-* **Response**: JSON document status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
-  * **Argument**: rev
-
-    * **Description**:  Current document revision
-    * **Optional**: no
-    * **Type**: string
-
-* **HTTP Headers**
-
-  * **Header**: ``Content-Length``
-
-    * **Description**: Length (bytes) of the attachment being uploaded
-    * **Optional**: no
-
-  * **Header**: ``Content-Type``
 
-    * **Description**: MIME type for the uploaded attachment
-    * **Optional**: no
+``/db/_design/design-doc/attachment``
+=====================================
 
-  * **Header**: ``If-Match``
+.. http:head:: /{db}/_design/{ddocname}/{attname}
 
-    * **Description**: Current revision of the document for validation
-    * **Optional**: yes
+  Returns the HTTP headers containing a minimal amount of information
+  about the specified attachment.
 
-Upload the supplied content as an attachment to the specified design
-document (``/_design/design-doc``). The ``attachment`` name provided
-must be a URL encoded string. You must also supply either the ``rev``
-query argument or the ``If-Match`` HTTP header for validation, and the
-HTTP headers (to set the attachment content type). The content type is
-used when the attachment is requested as the corresponding content-type
-in the returned document header.
+  .. seealso::
 
-For example, you could upload a simple text document using the following
-request:
+    :http:head:`/{db}/{docid}/{attname}`
 
-.. code-block:: http
+.. http:get:: /{db}/_design/{ddocname}/{attname}
 
-    PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e
-    Content-Length: 39
-    Content-Type: text/plain
+  Returns the file attachment associated with the design document.
+  The raw data of the associated attachment is returned (just as if you were
+  accessing a static file.
 
-    div.recipetitle {
-    font-weight: bold;
-    }
-
-Or by using the ``If-Match`` HTTP header:
-
-.. code-block:: http
-
-    PUT http://couchdb:5984/recipes/FishStew/basic
-    If-Match: 7-f7114d4d81124b223283f3e89eee043e
-    Content-Length: 39
-    Content-Type: text/plain
-
-    div.recipetitle {
-    font-weight: bold;
-    }
-
-The returned JSON contains the new document information:
-
-.. code-block:: javascript
-
-    {
-       "id" : "_design/recipes"
-       "ok" : true,
-       "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5",
-    }
-
-.. note::
-   Uploading an attachment updates the corresponding document revision.
-   Revisions are tracked for the parent document, not individual attachments.
+  .. seealso::
 
-.. _api/ddoc/attachment.delete:
+    :http:get:`/{db}/{docid}/{attname}`
 
-``DELETE /db/_design/design-doc/attachment``
-============================================
+.. http:put:: /{db}/_design/{ddocname}/{attname}
 
-* **Method**: ``DELETE /db/_design/design-doc/attachment``
-* **Request**: None
-* **Response**: JSON status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+  Uploads the supplied content as an attachment to the specified design
+  document. The attachment name provided must be a URL encoded string.
 
-  * **Argument**: rev
+  .. seealso::
 
-    * **Description**:  Current document revision
-    * **Optional**: no
-    * **Type**: string
+    :http:put:`/{db}/{docid}/{attname}`
 
-* **HTTP Headers**
+.. http:delete:: /{db}/_design/{ddocname}/{attname}
 
-  * **Header**: ``If-Match``
+  Deletes the attachment of the specified design document.
 
-    * **Description**: Current revision of the document for validation
-    * **Optional**: yes
+  .. seealso::
 
-* **Return Codes**:
+    :http:delete:`/{db}/{docid}/{attname}`
 
-  * **200**:
-    Attachment deleted successfully
-  * **409**:
-    Supplied revision is incorrect or missing
 
-Deletes the attachment ``attachment`` to the specified
-``_design/design-doc``. You must supply the ``rev`` argument with the
-current revision to delete the attachment.
-
-For example to delete the attachment ``view.css`` from the design
-document ``recipes``:
-
-.. code-block:: http
+.. _api/ddoc/info:
 
-    DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a
+``/db/_design/design-doc/_info``
+================================
 
-The returned JSON contains the updated revision information for the
-parent document:
+.. http:get:: /{db}/_design/{ddocname}/_info
 
-.. code-block:: javascript
+  Obtains information about the specified design document, including the index,
+  index size and current status of the design document and associated
+  index information.
 
-    {
-       "id" : "_design/recipes"
-       "ok" : true,
-       "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c",
-    }
+  :param db: Database name
+  :param ddocname: Design document name
+  :<header Accept: - :mimetype:`application/json`
+                   - :mimetype:`text/plain`
+  :>header Content-Type: - :mimetype:`application/json`
+                         - :mimetype:`text/plain; charset=utf-8`
+  :>json string name: Design document name
+  :>json object view_index: :ref:`api/ddoc/view_index_info`
+  :code 200: Request completed successfully
 
+  **Request**:
 
-.. _api/ddoc/info:
-.. _api/ddoc/info.get:
+  .. code-block:: http
 
-``GET /db/_design/design-doc/_info``
-====================================
+    GET /recipes/_design/recipe/_info HTTP/1.1
+    Accept: application/json
+    Host: localhost:5984
 
-* **Method**: ``GET /db/_design/design-doc/_info``
-* **Request**: None
-* **Response**: JSON of the design document information
-* **Admin Privileges Required**: no
+  **Response**:
 
-Obtains information about a given design document, including the index,
-index size and current status of the design document and associated
-index information.
+  .. code-block:: http
 
-For example, to get the information for the ``recipes`` design document:
-
-.. code-block:: http
-
-    GET http://couchdb:5984/recipes/_design/recipes/_info
+    HTTP/1.1 200 OK
+    Cache-Control: must-revalidate
+    Content-Length: 263
     Content-Type: application/json
-
-This returns the following JSON structure:
-
-.. code-block:: javascript
+    Date: Sat, 17 Aug 2013 12:54:17 GMT
+    Server: CouchDB/1.4.0 (Erlang OTP/R16B)
 
     {
-       "name" : "recipes"
-       "view_index" : {
-          "compact_running" : false,
-          "updater_running" : false,
-          "language" : "javascript",
-          "purge_seq" : 10,
-          "waiting_commit" : false,
-          "waiting_clients" : 0,
-          "signature" : "fc65594ee76087a3b8c726caf5b40687",
-          "update_seq" : 375031,
-          "disk_size" : 16491
-       },
+        "name": "recipe",
+        "view_index": {
+            "compact_running": false,
+            "data_size": 926691,
+            "disk_size": 1982704,
+            "language": "python",
+            "purge_seq": 0,
+            "signature": "a59a1bb13fdf8a8a584bc477919c97ac",
+            "update_seq": 12397,
+            "updater_running": false,
+            "waiting_clients": 0,
+            "waiting_commit": false
+        }
     }
 
-The individual fields in the returned JSON structure are detailed below:
-
-* **name**:  Name/ID of Design Document
-* **view_index**:  View Index
-
-  * **compact_running**:  Indicates whether a compaction routine is currently
-    running on the view
-  * **disk_size**:  Size in bytes of the view as stored on disk
-  * **language**:  Language for the defined views
-  * **purge_seq**:  The purge sequence that has been processed
-  * **signature**:  MD5 signature of the views for the design document
-  * **update_seq**:  The update sequence of the corresponding database that
-    has been indexed
-  * **updater_running**:  Indicates if the view is currently being updated
-  * **waiting_clients**:  Number of clients waiting on views from this design
-    document
-  * **waiting_commit**:  Indicates if there are outstanding commits to the
-    underlying database that need to processed
+
+.. _api/ddoc/view_index_info:
+
+View Index Information
+----------------------
+
+The response from :http:get:`/{db}/_design/{ddocname}/_info` contains
+``view_index`` (*object*) field with the next structure:
+
+* **compact_running** (*boolean*):  Indicates whether a compaction routine
+  is currently running on the view
+* **data_size** (*number*): Actual size in bytes of the view
+* **disk_size** (*number*): Size in bytes of the view as stored on disk
+* **language** (*string*): Language for the defined views
+* **purge_seq** (*number*): The purge sequence that has been processed
+* **signature** (*string*): MD5 signature of the views for the design document
+* **update_seq** (*number*): The update sequence of the corresponding database
+  that has been indexed
+* **updater_running** (*boolean*): Indicates if the view is currently
+  being updated
+* **waiting_clients** (*number*): Number of clients waiting on views from
+  this design document
+* **waiting_commit** (*boolean*): Indicates if there are outstanding commits
+  to the underlying database that need to processed

http://git-wip-us.apache.org/repos/asf/couchdb/blob/a436f83c/share/doc/src/query-server/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-server/index.rst b/share/doc/src/query-server/index.rst
index b16e0ac..835ba1b 100644
--- a/share/doc/src/query-server/index.rst
+++ b/share/doc/src/query-server/index.rst
@@ -10,6 +10,7 @@
 .. License for the specific language governing permissions and limitations under
 .. the License.
 
+.. _query-server:
 
 ============
 Query Server


Mime
View raw message