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/09/28 13:09:46 UTC
[1/9] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 5522488
Updated Branches:
refs/heads/1781-reorganize-and-improve-docs a169ab674 -> 5522488e8
Update Fauxton docs links.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/a00c6a48
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/a00c6a48
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/a00c6a48
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: a00c6a48b059f8c48adf56cf7836f639fa7446ec
Parents: a169ab6
Author: Alexander Shorin <kx...@apache.org>
Authored: Fri Sep 27 22:37:48 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 08:52:31 2013 +0400
----------------------------------------------------------------------
src/fauxton/app/helpers.js | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a00c6a48/src/fauxton/app/helpers.js
----------------------------------------------------------------------
diff --git a/src/fauxton/app/helpers.js b/src/fauxton/app/helpers.js
index d6ea966..a8e0698 100644
--- a/src/fauxton/app/helpers.js
+++ b/src/fauxton/app/helpers.js
@@ -36,13 +36,13 @@ function() {
// update the URLs in documentation_urls.js
Helpers.docs = {
"docs": "http://docs.couchdb.org/en/latest/index.html",
- "replication_doc": "http://docs.couchdb.org/en/latest/replicator.html#basics",
- "design_doc": "http://docs.couchdb.org/en/latest/ddocs.html#design-docs",
- "view_functions": "http://docs.couchdb.org/en/latest/ddocs.html#view-functions",
- "map_functions": "http://docs.couchdb.org/en/latest/ddocs.html#map-functions",
- "reduce_functions": "http://docs.couchdb.org/en/latest/ddocs.html#reduce-and-rereduce-functions",
- "api_reference": "http://docs.couchdb.org/en/latest/api-basics.html?highlight=api",
- "database_permission": "http://docs.couchdb.org/en/latest/api/database.html#get-db-security"
+ "replication_doc": "http://docs.couchdb.org/en/latest/replication/replicator.html#basics",
+ "design_doc": "http://docs.couchdb.org/en/latest/couchapp/ddocs.html#design-docs",
+ "view_functions": "http://docs.couchdb.org/en/latest/couchapp/ddocs.html#view-functions",
+ "map_functions": "http://docs.couchdb.org/en/latest/couchapp/ddocs.html#map-functions",
+ "reduce_functions": "http://docs.couchdb.org/en/latest/couchapp/ddocs.html#reduce-and-rereduce-functions",
+ "api_reference": "http://docs.couchdb.org/en/latest/http-api.html",
+ "database_permission": "http://docs.couchdb.org/en/latest/api/database/security.html#db-security"
};
Helpers.getDocUrl = function(doc){
[5/9] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 5522488
Posted by kx...@apache.org.
Add about page with CouchDB license.
While sources are ships with all license bits, documentation artifacts lack of such.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/6b50511d
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/6b50511d
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/6b50511d
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 6b50511d88d29d50e0b9b927d239e337087f4e4b
Parents: 088ea1e
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 10:43:00 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 10:43:00 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +++
share/doc/src/about.rst | 25 +++++++++++++++++++++++++
share/doc/src/contents.rst | 1 +
3 files changed, 29 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6b50511d/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 5a9441f..c83e392 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -139,6 +139,7 @@ html_files = \
html/_sources/whatsnew/1.3.txt \
html/_sources/whatsnew/1.4.txt \
html/_sources/whatsnew/index.txt \
+ html/_sources/about.txt \
html/_sources/contents.txt \
html/_sources/contributing.txt \
html/_sources/externals.txt \
@@ -256,6 +257,7 @@ html_files = \
html/whatsnew/1.3.html \
html/whatsnew/1.4.html \
html/whatsnew/index.html \
+ html/about.html \
html/contents.html \
html/externals.html \
html/json-structure.html \
@@ -395,6 +397,7 @@ src_files = \
../src/whatsnew/1.3.rst \
../src/whatsnew/1.4.rst \
../src/whatsnew/index.rst \
+ ../src/about.rst \
../src/contents.rst \
../src/contributing.rst \
../src/externals.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6b50511d/share/doc/src/about.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/about.rst b/share/doc/src/about.rst
new file mode 100644
index 0000000..fe24c61
--- /dev/null
+++ b/share/doc/src/about.rst
@@ -0,0 +1,25 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+
+.. _about:
+
+===========================
+About CouchDB Documentation
+===========================
+
+License
+=======
+
+.. literalinclude:: ../../../LICENSE
+ :lines: 1-202
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6b50511d/share/doc/src/contents.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/contents.rst b/share/doc/src/contents.rst
index 700e90a..0b38b73 100644
--- a/share/doc/src/contents.rst
+++ b/share/doc/src/contents.rst
@@ -32,6 +32,7 @@
contributing
whatsnew/index
cve/index
+ about
.. This is how you get a TM sign into a link. Haha. Seriously.
.. |Apache CouchDB(TM)| unicode:: Apache U+0020 CouchDB U+2122
[6/9] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 5522488
Posted by kx...@apache.org.
Prepare for 1.5.0 release.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/5fe58936
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/5fe58936
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/5fe58936
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 5fe58936ae6bf4e72e43380d517c057f7cabd1c8
Parents: 6b50511
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 10:45:05 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 10:45:05 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +++
share/doc/src/whatsnew/1.5.rst | 31 +++++++++++++++++++++++++++++++
share/doc/src/whatsnew/index.rst | 2 +-
3 files changed, 35 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5fe58936/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index c83e392..870976a 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -138,6 +138,7 @@ html_files = \
html/_sources/whatsnew/1.2.txt \
html/_sources/whatsnew/1.3.txt \
html/_sources/whatsnew/1.4.txt \
+ html/_sources/whatsnew/1.5.txt \
html/_sources/whatsnew/index.txt \
html/_sources/about.txt \
html/_sources/contents.txt \
@@ -256,6 +257,7 @@ html_files = \
html/whatsnew/1.2.html \
html/whatsnew/1.3.html \
html/whatsnew/1.4.html \
+ html/whatsnew/1.5.html \
html/whatsnew/index.html \
html/about.html \
html/contents.html \
@@ -396,6 +398,7 @@ src_files = \
../src/whatsnew/1.2.rst \
../src/whatsnew/1.3.rst \
../src/whatsnew/1.4.rst \
+ ../src/whatsnew/1.5.rst \
../src/whatsnew/index.rst \
../src/about.rst \
../src/contents.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5fe58936/share/doc/src/whatsnew/1.5.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/whatsnew/1.5.rst b/share/doc/src/whatsnew/1.5.rst
new file mode 100644
index 0000000..f2ce86a
--- /dev/null
+++ b/share/doc/src/whatsnew/1.5.rst
@@ -0,0 +1,31 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+
+.. _release/1.5.x:
+
+============
+1.5.x Branch
+============
+
+.. contents::
+ :depth: 1
+ :local:
+
+.. _release/1.5.0:
+
+Version 1.5.0
+=============
+
+.. warning::
+
+ This version is not released yet.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5fe58936/share/doc/src/whatsnew/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/whatsnew/index.rst b/share/doc/src/whatsnew/index.rst
index a69a75e..50cc9ec 100644
--- a/share/doc/src/whatsnew/index.rst
+++ b/share/doc/src/whatsnew/index.rst
@@ -19,7 +19,7 @@ Release History
.. toctree::
:glob:
- ../cve/index
+ 1.5
1.4
1.3
1.2
[9/9] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 5522488
Posted by kx...@apache.org.
Make HTTP domain default one.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/5522488e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/5522488e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/5522488e
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 5522488e8c2e0772aa5f2844d0c557f3f17c5586
Parents: 598ccd4
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 13:33:53 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 13:33:53 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/bulk-api.rst | 2 +-
share/doc/src/api/database/changes.rst | 6 ++---
share/doc/src/api/database/common.rst | 4 ++--
share/doc/src/api/database/compact.rst | 10 ++++----
share/doc/src/api/database/misc.rst | 2 +-
share/doc/src/api/database/security.rst | 2 +-
share/doc/src/api/ddoc/common.rst | 24 +++++++++----------
share/doc/src/api/ddoc/rewrites.rst | 2 +-
share/doc/src/api/ddoc/views.rst | 10 ++++----
share/doc/src/api/document/attachments.rst | 22 ++++++++---------
share/doc/src/api/document/common.rst | 32 ++++++++++++-------------
share/doc/src/api/local.rst | 8 +++----
share/doc/src/api/server/common.rst | 4 ++--
share/doc/src/conf.py | 2 ++
share/doc/src/config/compaction.rst | 2 +-
share/doc/src/intro/api.rst | 1 -
share/doc/src/maintenance/compaction.rst | 16 ++++++-------
share/doc/src/maintenance/performance.rst | 2 --
share/doc/src/query-server/erlang.rst | 1 +
share/doc/src/replication/conflicts.rst | 6 ++---
share/doc/src/replication/protocol.rst | 20 ++++++++--------
21 files changed, 89 insertions(+), 89 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 eb49a28..87233df 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -137,7 +137,7 @@
The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
selected from the database. This enables you to request multiple
- documents in a single request, in place of multiple :http:get:`/{db}/{docid}`
+ documents in a single request, in place of multiple :get:`/{db}/{docid}`
requests.
The request body should contain a list of the keys to be returned as an
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 f144f33..f2ad9b7 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -39,7 +39,7 @@
previous connection. Overrides `since` query parameter.
:query array doc_ids: List of document IDs to filter the changes feed as
valid JSON array. Used with :ref:`_doc_ids <changes/filter/doc_ids>` filter.
- Since `length of URL is limited`_, you better use :http:post:`/{db}/_changes`
+ Since `length of URL is limited`_, you better use :post:`/{db}/_changes`
method instead.
:query boolean conflicts: Includes `conflicts` information in response.
Ignored if `include_docs` isn't ``true``. Default is ``false``.
@@ -165,7 +165,7 @@
.. http:post:: /{db}/_changes
Requests the database changes feed in the same way as
- :http:get:`/{db}/_changes` does, but this method is widely used with
+ :get:`/{db}/_changes` does, but this method is widely used with
``?filter=_doc_ids`` query parameter and allows to pass larger list of
document IDs to filter.
@@ -421,7 +421,7 @@ _doc_ids
This filter accepts only changes for documents which ID in specified in
``doc_ids`` query parameter or payload's object array. See
-:http:post:`/{db}/_changes` for an example.
+:post:`/{db}/_changes` for an example.
.. _changes/filter/design:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 5265919..c374625 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -376,8 +376,8 @@ the risk of the documents not being stored in the event of a failure,
since the documents are not written to disk immediately.
To use the batched mode, append the ``batch=ok`` query argument to the
-URL of the ``PUT`` or :http:post:`/{db}` request. The CouchDB server will
-respond with a HTTP :http:statuscode:`202` response code immediately.
+URL of the ``PUT`` or :post:`/{db}` request. The CouchDB server will
+respond with a HTTP :statuscode:`202` response code immediately.
.. note::
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 f7289e5..d2b90d7 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -38,7 +38,7 @@
You can determine if the compaction process is operating on a database
by obtaining the database meta information, the ``compact_running``
value of the returned database structure will be set to true. See
- :http:get:`/{db}`.
+ :get:`/{db}`.
You can also obtain a list of running processes to determine whether
compaction is currently running. See :ref:`api/server/active_tasks`.
@@ -53,7 +53,7 @@
:code 202: Compaction request has been accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
@@ -105,7 +105,7 @@
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
:code 404: Design document not found
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
@@ -162,7 +162,7 @@
:>json boolean ok: Operation status
:code 201: Commit completed successfully
:code 400: Invalid database name
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
@@ -212,7 +212,7 @@
:code 202: Compaction request has been accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 ad46e15..e69ce8a 100644
--- a/share/doc/src/api/database/misc.rst
+++ b/share/doc/src/api/database/misc.rst
@@ -62,7 +62,7 @@
:>json object purged: Mapping of document ID to list of purged revisions
:code 200: Request completed successfully
:code 400: Invalid database name or JSON payload
- :code 415: Bad :http:header:`Content-Type` value
+ :code 415: Bad :header:`Content-Type` value
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 ee95ee4..7bdf88e 100644
--- a/share/doc/src/api/database/security.rst
+++ b/share/doc/src/api/database/security.rst
@@ -53,7 +53,7 @@
If there are any member names or roles defined for a database, then only
authenticated users having a matching name or role are allowed to
- read documents from the database (or do a :http:get:`/{db}` call).
+ read documents from the database (or do a :get:`/{db}` call).
.. note::
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 79c7357..16cfffc 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -23,7 +23,7 @@
.. seealso::
- :http:head:`/{db}/{docid}`
+ :head:`/{db}/{docid}`
.. http:get:: /{db}/_design/{ddoc}
@@ -34,12 +34,12 @@
.. seealso::
- :http:get:`/{db}/{docid}`
+ :get:`/{db}/{docid}`
.. http:put:: /{db}/_design/{ddoc}
- The :http:method:`PUT` method creates a new named design document, or creates
+ The :method:`PUT` method creates a new named design document, or creates
a new revision of the existing design document.
The design documents have some agreement upon their fields and structure.
@@ -64,7 +64,7 @@
.. seealso::
- :http:put:`/{db}/{docid}`
+ :put:`/{db}/{docid}`
.. http:delete:: /{db}/_design/{ddoc}
@@ -75,11 +75,11 @@
.. seealso::
- :http:delete:`/{db}/{docid}`
+ :delete:`/{db}/{docid}`
.. http:copy:: /{db}/_design/{ddoc}
- The :http:method:`COPY` (which is non-standard HTTP) copies an existing
+ The :method:`COPY` (which is non-standard HTTP) copies an existing
design document to a new or existing one.
.. note::
@@ -89,7 +89,7 @@
.. seealso::
- :http:copy:`/{db}/{docid}`
+ :copy:`/{db}/{docid}`
.. _api/ddoc/attachment:
@@ -104,7 +104,7 @@
.. seealso::
- :http:head:`/{db}/{docid}/{attname}`
+ :head:`/{db}/{docid}/{attname}`
.. http:get:: /{db}/_design/{ddoc}/{attname}
@@ -114,7 +114,7 @@
.. seealso::
- :http:get:`/{db}/{docid}/{attname}`
+ :get:`/{db}/{docid}/{attname}`
.. http:put:: /{db}/_design/{ddoc}/{attname}
@@ -123,7 +123,7 @@
.. seealso::
- :http:put:`/{db}/{docid}/{attname}`
+ :put:`/{db}/{docid}/{attname}`
.. http:delete:: /{db}/_design/{ddoc}/{attname}
@@ -131,7 +131,7 @@
.. seealso::
- :http:delete:`/{db}/{docid}/{attname}`
+ :delete:`/{db}/{docid}/{attname}`
.. _api/ddoc/info:
@@ -196,7 +196,7 @@
View Index Information
----------------------
-The response from :http:get:`/{db}/_design/{ddoc}/_info` contains
+The response from :get:`/{db}/_design/{ddoc}/_info` contains
``view_index`` (*object*) field with the next structure:
* **compact_running** (*boolean*): Indicates whether a compaction routine
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 61eebed..d6e83a9 100644
--- a/share/doc/src/api/ddoc/rewrites.rst
+++ b/share/doc/src/api/ddoc/rewrites.rst
@@ -52,7 +52,7 @@
The pattern matching is done by first matching the request method to a rule.
By default all methods match a rule. (method is equal to ``"*"`` by default).
Then It will try to match the path to one rule. If no rule match, then a
- :http:statuscode:`404` response returned.
+ :statuscode:`404` response returned.
Once a rule is found we rewrite the request url using the ``to`` and ``query``
fields. The identified token are matched to the rule and will replace var.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 7834539..8683085 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -126,11 +126,11 @@
.. http:post:: /{db}/_design/{ddoc}/_view/{view}
Executes the specified view function from the specified design document.
- Unlike the :http:get:`/{db}/_design/{ddoc}/_view/{view}` method
- for accessing views, the :http:method:`POST` method supports the specification
+ Unlike the :get:`/{db}/_design/{ddoc}/_view/{view}` method
+ for accessing views, the :method:`POST` method supports the specification
of explicit keys to be retrieved from the view results. The remainder of the
- :http:method:`POST` view functionality is identical to the
- :http:get:`/{db}/_design/{ddoc}/_view/{view}` API.
+ :method:`POST` view functionality is identical to the
+ :get:`/{db}/_design/{ddoc}/_view/{view}` API.
**Request**:
@@ -295,7 +295,7 @@ In addition to using stale views, you can also make use of the
view information including the update sequence of the database from
which the view was generated. The returned value can be compared this to
the current update sequence exposed in the database information
-(returned by :http:get:`/{db}`).
+(returned by :get:`/{db}`).
.. _api/ddoc/view/sorting:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 34526fc..c26b561 100644
--- a/share/doc/src/api/document/attachments.rst
+++ b/share/doc/src/api/document/attachments.rst
@@ -20,9 +20,9 @@
Returns the HTTP headers containing a minimal amount of information
about the specified attachment. The method supports the same query
- arguments as the :http:get:`/{db}/{docid}/{attname}` method, but only
+ arguments as the :get:`/{db}/{docid}/{attname}` method, but only
the header information (including attachment size, encoding and the MD5 hash
- as an :http:header:`ETag`), is returned.
+ as an :header:`ETag`), is returned.
:param db: Database name
:param docid: Document ID
@@ -41,8 +41,8 @@
:>header Content-MD5: Base64 encoded MD5 binary digest
:>header ETag: Double quoted base64 encoded MD5 binary digest
:code 200: Attachment exists
- :code 304: Attachment wasn't modified if :http:header:`ETag` equals specified
- :http:header:`If-None-Match` header
+ :code 304: Attachment wasn't modified if :header:`ETag` equals specified
+ :header:`If-None-Match` header
:code 401: Read privilege required
:code 404: Specified database, document or attachment was not found
@@ -73,7 +73,7 @@
Returns the file attachment associated with the document.
The raw data of the associated attachment is returned (just as if you were
- accessing a static file. The returned :http:header:`Content-Type`
+ accessing a static file. The returned :header:`Content-Type`
will be the same as the content type set when the document attachment
was submitted into the database.
@@ -95,8 +95,8 @@
:>header ETag: Double quoted base64 encoded MD5 binary digest
:response: Stored content
:code 200: Attachment exists
- :code 304: Attachment wasn't modified if :http:header:`ETag` equals specified
- :http:header:`If-None-Match` header
+ :code 304: Attachment wasn't modified if :header:`ETag` equals specified
+ :header:`If-None-Match` header
:code 401: Read privilege required
:code 404: Specified database, document or attachment was not found
@@ -105,7 +105,7 @@
Uploads the supplied content as an attachment to the specified document.
The attachment name provided must be a URL encoded string. You must also
- supply either the ``rev`` query argument or the :http:header:`If-Match`
+ supply either the ``rev`` query argument or the :header:`If-Match`
HTTP header for validation, and the HTTP headers (to set the attachment
content type).
@@ -184,7 +184,7 @@
.. http:delete:: /{db}/{docid}/{attname}
Deletes the attachment ``attachment`` of the specified ``doc``. You must
- supply the ``rev`` query parameter or :http:header:`If-Match` with the current
+ supply the ``rev`` query parameter or :header:`If-Match` with the current
revision to delete the attachment.
.. note::
@@ -224,7 +224,7 @@
Host: localhost:5984
Alternatively, instead of ``rev`` query parameter you may use
- :http:header:`If-Match` header:
+ :header:`If-Match` header:
.. code-block:: http
@@ -265,7 +265,7 @@ This is just a real quick run through how this looks under the hood.
Usually, you will have larger binary files to serve from CouchDB, like
MP3s and videos, but to make things a little more obvious, I use a text
file here (Note that I use the :mimetype:`application/octet-stream`
-:http:header`Content-Type` instead of :mimetype:`text/plain`).
+:header`Content-Type` instead of :mimetype:`text/plain`).
.. code-block:: bash
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 4ad854e..6687ebc 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -20,15 +20,15 @@
Returns the HTTP Headers containing a minimal amount of information
about the specified document. The method supports the same query
- arguments as the :http:get:`/{db}/{docid}` method, but only the header
+ arguments as the :get:`/{db}/{docid}` method, but only the header
information (including document size, and the revision as an ETag), is
returned.
- The :http:header:`ETag` header shows the current revision for the requested
- document, and the :http:header:`Content-Length` specifies the length of the
+ The :header:`ETag` header shows the current revision for the requested
+ document, and the :header:`Content-Length` specifies the length of the
data, if the document were requested in full.
- Adding any of the query arguments (see :http:get:`/{db}/{docid}`), then the
+ Adding any of the query arguments (see :get:`/{db}/{docid}`), then the
resulting HTTP Headers will correspond to what would be returned.
:param db: Database name
@@ -166,8 +166,8 @@
.. http:put:: /{db}/{docid}
- The :http:method:`PUT` method creates a new named document, or creates a new
- revision of the existing document. Unlike the :http:post:`/{db}` method, you
+ The :method:`PUT` method creates a new named document, or creates a new
+ revision of the existing document. Unlike the :post:`/{db}` method, you
must specify the document ID in the request URL.
:param db: Database name
@@ -280,7 +280,7 @@
Host: localhost:5984
Alternatively, instead of ``rev`` query parameter you may use
- :http:header:`If-Match` header:
+ :header:`If-Match` header:
.. code-block:: http
@@ -310,11 +310,11 @@
.. http:copy:: /{db}/{docid}
- The :http:method:`COPY` (which is non-standard HTTP) copies an existing
+ The :method:`COPY` (which is non-standard HTTP) copies an existing
document to a new or existing document.
The source document is specified on the request line, with the
- :http:header:`Destination` header of the request specifying the target
+ :header:`Destination` header of the request specifying the target
document.
:param db: Database name
@@ -718,11 +718,11 @@ just inline base64 encoded attachments data into the document body:
Alternatively, you can upload a document with attachments more efficiently in
:mimetype:`multipart/related` format. This avoids having to Base64-encode
the attachments, saving CPU and bandwidth. To do this, set the
-:http:header:`Content-Type` header of the :http:put:`/{db}/{docid}` request to
+:header:`Content-Type` header of the :put:`/{db}/{docid}` request to
:mimetype:`multipart/related`.
The first MIME body is the document itself, which should have its own
-:http:header:`Content-Type` of :mimetype:`application/json"`. It also should
+:header:`Content-Type` of :mimetype:`application/json"`. It also should
include an ``_attachments`` metadata object in which each attachment object
has a key ``follows`` with value ``true``.
@@ -975,9 +975,9 @@ requested.
Retrieving Deleted Documents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-CouchDB doesn't actually deletes documents via :http:delete:`/{db}/{docid}`.
+CouchDB doesn't actually deletes documents via :delete:`/{db}/{docid}`.
Instead of this, it leaves tombstone with very basic information about document.
-If you just :http:get:`/{db}/{docid}` CouchDB returns :http:statuscode:`404`
+If you just :get:`/{db}/{docid}` CouchDB returns :statuscode:`404`
response:
**Request**:
@@ -1005,7 +1005,7 @@ response:
}
However, you may retrieve document's tombstone by using ``rev`` query parameter
-with :http:get:`/{db}/{docid}` request:
+with :get:`/{db}/{docid}` request:
**Request**:
@@ -1110,7 +1110,7 @@ Copying from a Specific Revision
--------------------------------
To copy *from* a specific version, use the ``rev`` argument to the query
-string or :http:header:`If-Match`:
+string or :header:`If-Match`:
**Request**:
@@ -1147,7 +1147,7 @@ Copying to an Existing Document
To copy to an existing document, you must specify the current revision
string for the target document by appending the ``rev`` parameter to the
-:http:header:`Destination` header string.
+:header:`Destination` header string.
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/api/local.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
index 0fb6d6c..970523e 100644
--- a/share/doc/src/api/local.rst
+++ b/share/doc/src/api/local.rst
@@ -59,22 +59,22 @@ A list of the available methods and URL paths are provided below:
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 :http:get:`/{db}/{docid}`.
+ document is not replicated. See :get:`/{db}/{docid}`.
.. http:put:: /{db}/_local/{docid}
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 :http:put:`/{db}/{docid}`.
+ document is not replicated. See :put:`/{db}/{docid}`.
.. http:delete:: /{db}/_local/{docid}
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 :http:delete:`/{db}/{docid}`.
+ document is not replicated. See :delete:`/{db}/{docid}`.
.. http:copy:: /{db}/_local/{docid}
Copies the specified local document. The semantics are identical to
copying a standard document in the specified database, except that the
- document is not replicated. See :http:copy:`/{db}/{docid}`.
+ document is not replicated. See :copy:`/{db}/{docid}`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/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 3c0686c..fda74f5 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -676,7 +676,7 @@ a 404 error.
:code 202: Server goes to restart (there is no guarantee that it will be
alive after)
:code 401: CouchDB Server Administrator privileges required
- :code 415: Bad request`s :http:header:`Content-Type`
+ :code 415: Bad request`s :header:`Content-Type`
**Request**:
@@ -892,7 +892,7 @@ structure is as follows:
Accesses the built-in Futon administration interface for CouchDB.
:>header Location: New URI location
- :code 301: Redirects to :http:get:`/_utils/`
+ :code 301: Redirects to :get:`/_utils/`
.. http:get:: /_utils/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 6cdb9ef..805f87d 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -64,6 +64,8 @@ copyright = '%d, %s' % (
highlight_language = "json"
+primary_domain = "http"
+
pygments_style = "sphinx"
html_theme = "couchdb"
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/config/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/compaction.rst b/share/doc/src/config/compaction.rst
index 737c29d..0393d8c 100644
--- a/share/doc/src/config/compaction.rst
+++ b/share/doc/src/config/compaction.rst
@@ -76,7 +76,7 @@ Possible parameters:
(file_size - data_size) / file_size * 100
The data_size and file_size values can be obtained when
- querying :http:get:`/{db}`.
+ querying :get:`/{db}`.
- ``view_fragmentation``: If the ratio of legacy data, including metadata, to
current data in a view index file size is equal to or greater then this
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/intro/api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/api.rst b/share/doc/src/intro/api.rst
index 9779ea9..67c8f5b 100644
--- a/share/doc/src/intro/api.rst
+++ b/share/doc/src/intro/api.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. default-domain:: http
.. _intro/api:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/maintenance/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/compaction.rst b/share/doc/src/maintenance/compaction.rst
index a24e008..3e3ddfc 100644
--- a/share/doc/src/maintenance/compaction.rst
+++ b/share/doc/src/maintenance/compaction.rst
@@ -40,16 +40,16 @@ Database compaction compresses the database file by removing unused file
sections created during updates. Old documents revisions are replaced with
small amount of metadata called `tombstone` which are used for conflicts
resolution during replication. The number of stored revisions
-(and their `tombstones`) can be configured by using the :http:get:`_revs_limit
+(and their `tombstones`) can be configured by using the :get:`_revs_limit
</{db}/_revs_limit>` URL endpoint.
Compaction is manually triggered operation per database and runs as a background
task. To start it for specific database there is need to send HTTP
-:http:post:`/{db}/_compact` sub-resource of the target database::
+:post:`/{db}/_compact` sub-resource of the target database::
curl -H "Content-Type: application/json" -X POST http://localhost:5984/my_db/_compact
-On success, HTTP status :http:statuscode:`202` is returned immediately:
+On success, HTTP status :statuscode:`202` is returned immediately:
.. code-block:: http
@@ -65,9 +65,9 @@ On success, HTTP status :http:statuscode:`202` is returned immediately:
{"ok":true}
Although the request body is not used you must still specify
-:http:header:`Content-Type` header with :mimetype:`application/json` value
+:header:`Content-Type` header with :mimetype:`application/json` value
for the request. If you don't, you will be aware about with HTTP status
-:http:statuscode:`415` response:
+:statuscode:`415` response:
.. code-block:: http
@@ -111,7 +111,7 @@ information about it via :ref:`database information resource <api/db>`::
Note that ``compaction_running`` field is ``true`` indicating that compaction
is actually running. To track the compaction progress you may query the
-:http:get:`_active_tasks </_active_tasks>` resource::
+:get:`_active_tasks </_active_tasks>` resource::
curl http://localhost:5984/my_db
@@ -145,7 +145,7 @@ Views Compaction
`Views` are also need compaction like databases, unlike databases views
are compacted by groups per `design document`. To start their compaction there
-is need to send HTTP :http:post:`/{db}/_compact/{ddoc}` request::
+is need to send HTTP :post:`/{db}/_compact/{ddoc}` request::
curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_compact/designname
@@ -154,7 +154,7 @@ is need to send HTTP :http:post:`/{db}/_compact/{ddoc}` request::
{"ok":true}
This compacts the view index from the current version of the specified design
-document. The HTTP response code is :http:statuscode:`202`
+document. The HTTP response code is :statuscode:`202`
(like :ref:`compaction for databases <compact/db>`) and a compaction background
task will be created.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/maintenance/performance.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/performance.rst b/share/doc/src/maintenance/performance.rst
index 918b1cf..9495cb1 100644
--- a/share/doc/src/maintenance/performance.rst
+++ b/share/doc/src/maintenance/performance.rst
@@ -10,8 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. default-domain:: http
-
.. _performance:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/query-server/erlang.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-server/erlang.rst b/share/doc/src/query-server/erlang.rst
index 21f2399..165a341 100644
--- a/share/doc/src/query-server/erlang.rst
+++ b/share/doc/src/query-server/erlang.rst
@@ -10,6 +10,7 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: js
.. _query-server/erlang:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/replication/conflicts.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/conflicts.rst b/share/doc/src/replication/conflicts.rst
index 354c286..2d01a8c 100644
--- a/share/doc/src/replication/conflicts.rst
+++ b/share/doc/src/replication/conflicts.rst
@@ -109,10 +109,10 @@ Conflict avoidance
==================
When working on a single node, CouchDB will avoid creating conflicting revisions
-by returning a :http:statuscode:`409` error. This is because, when you
+by returning a :statuscode:`409` error. This is because, when you
PUT a new version of a document, you must give the ``_rev`` of the previous
version. If that ``_rev`` has already been superseded, the update is rejected
-with a :http:statuscode:`409` response.
+with a :statuscode:`409` response.
So imagine two users on the same node are fetching Bob's business card, updating
it concurrently, and writing it back:
@@ -238,7 +238,7 @@ arbitrarily large.
Working with conflicting documents
==================================
-The basic :http:get:`/{doc}/{docid}` operation will not show you any
+The basic :get:`/{doc}/{docid}` operation will not show you any
information about conflicts. You see only the deterministically-chosen winner,
and get no indication as to whether other conflicting revisions exist or not:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5522488e/share/doc/src/replication/protocol.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/protocol.rst b/share/doc/src/replication/protocol.rst
index 3aae5c1..10ba243 100644
--- a/share/doc/src/replication/protocol.rst
+++ b/share/doc/src/replication/protocol.rst
@@ -151,26 +151,26 @@ Optimisations
API Reference
-------------
-- :http:head:`/{db}` -- Check Database existence
-- :http:post:`/{db}/_ensure_full_commit` -- Ensure that all changes are stored
+- :head:`/{db}` -- Check Database existence
+- :post:`/{db}/_ensure_full_commit` -- Ensure that all changes are stored
on disk
-- :http:get:`/{db}/_local/{id}` -- Read the last Checkpoint
-- :http:put:`/{db}/_local/{id}` -- Save a new Checkpoint
+- :get:`/{db}/_local/{id}` -- Read the last Checkpoint
+- :put:`/{db}/_local/{id}` -- Save a new Checkpoint
Push Only
~~~~~~~~~
-- :http:put:`/{db}` -- Create Target if it not exists and option was provided
-- :http:post:`/{db}/_revs_diff` -- Locate Revisions that are not known to the
+- :put:`/{db}` -- Create Target if it not exists and option was provided
+- :post:`/{db}/_revs_diff` -- Locate Revisions that are not known to the
Target
-- :http:post:`/{db}/_bulk_docs` -- Upload Revisions to the Target
-- :http:put:`/{db}/{docid}`?new_edits=false -- Upload a single Document with
+- :post:`/{db}/_bulk_docs` -- Upload Revisions to the Target
+- :put:`/{db}/{docid}`?new_edits=false -- Upload a single Document with
attachments to the Target
Pull Only
~~~~~~~~~
-- :http:get:`/{db}/_changes` -- Locate changes since on Source the last pull.
+- :get:`/{db}/_changes` -- Locate changes since on Source the last pull.
The request uses next query parameters:
- ``style=all_docs``
@@ -179,7 +179,7 @@ Pull Only
- ``limit=limit``
- ``heartbeat=heartbeat``
-- :http:get:`/{db}/{docid}` -- Retrieve a single Document from Source with attachments.
+- :get:`/{db}/{docid}` -- Retrieve a single Document from Source with attachments.
The request uses next query parameters:
- ``open_revs=revid`` - where ``revid`` is the actual Document Revision at the
[8/9] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 5522488
Posted by kx...@apache.org.
Add notes about multipart/related API requests.
COUCHDB-1168
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/598ccd4d
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/598ccd4d
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/598ccd4d
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 598ccd4d87be97d3cbed8ab1773d5b79f0a9d5f7
Parents: 9a18fd2
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 13:18:50 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 13:18:50 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/document/common.rst | 150 +++++++++++++++++++++++++++++
1 file changed, 150 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/598ccd4d/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 03b1de1..4ad854e 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -570,6 +570,59 @@ query parameter:
}
+Efficient Multiple Attachments Retrieving
+`````````````````````````````````````````
+
+As you had noted above, retrieving document with ``attachements=true`` returns
+large JSON object where all attachments are included. While you document and
+files are smaller it's ok, but if you have attached something bigger like media
+files (audio/video), parsing such response might be very expensive.
+
+To solve this problem, CouchDB allows to get documents in
+:mimetype:`multipart/related` format:
+
+**Request**:
+
+.. code-block:: http
+
+ GET /recipes/secret?attachments=true HTTP/1.1
+ Accept: multipart/related
+ Host: localhost:5984
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Length: 538
+ Content-Type: multipart/related; boundary="e89b3e29388aef23453450d10e5aaed0"
+ Date: Sat, 28 Sep 2013 08:08:22 GMT
+ ETag: "2-c1c6c44c4bc3c9344b037c8690468605"
+ Server: CouchDB (Erlang OTP)
+
+ --e89b3e29388aef23453450d10e5aaed0
+ Content-Type: application/json
+
+ {"_id":"secret","_rev":"2-c1c6c44c4bc3c9344b037c8690468605","_attachments":{"recipe.txt":{"content_type":"text/plain","revpos":2,"digest":"md5-HV9aXJdEnu0xnMQYTKgOFA==","length":86,"follows":true}}}
+ --e89b3e29388aef23453450d10e5aaed0
+ Content-Disposition: attachment; filename="recipe.txt"
+ Content-Type: text/plain
+ Content-Length: 86
+
+ 1. Take R
+ 2. Take E
+ 3. Mix with L
+ 4. Add some A
+ 5. Serve with X
+
+ --e89b3e29388aef23453450d10e5aaed0--
+
+In this response the document contains only attachments stub information and
+quite short while all attachments goes as separate entities which reduces
+memory footprint and processing overhead (you'd noticed, that attachment content
+goes as raw data, not in base64 encoding, right?).
+
+
Retrieving Attachments Encoding Info
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -636,6 +689,103 @@ about compressed attachments size and used codec.
}
+Creating Multiple Attachments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To create a document with multiple attachments with single request you need
+just inline base64 encoded attachments data into the document body:
+
+.. code-block:: javascript
+
+ {
+ "_id":"multiple_attachments",
+ "_attachments":
+ {
+ "foo.txt":
+ {
+ "content_type":"text\/plain",
+ "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
+ },
+
+ "bar.txt":
+ {
+ "content_type":"text\/plain",
+ "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
+ }
+ }
+ }
+
+Alternatively, you can upload a document with attachments more efficiently in
+:mimetype:`multipart/related` format. This avoids having to Base64-encode
+the attachments, saving CPU and bandwidth. To do this, set the
+:http:header:`Content-Type` header of the :http:put:`/{db}/{docid}` request to
+:mimetype:`multipart/related`.
+
+The first MIME body is the document itself, which should have its own
+:http:header:`Content-Type` of :mimetype:`application/json"`. It also should
+include an ``_attachments`` metadata object in which each attachment object
+has a key ``follows`` with value ``true``.
+
+The subsequent MIME bodies are the attachments.
+
+**Request**:
+
+.. code-block:: http
+
+ PUT /temp/somedoc HTTP/1.1
+ Accept: application/json
+ Content-Length: 372
+ Content-Type: multipart/related;boundary="abc123"
+ Host: localhost:5984
+ User-Agent: HTTPie/0.6.0
+
+ --abc123
+ Content-Type: application/json
+
+ {
+ "body": "This is a body.",
+ "_attachments": {
+ "foo.txt": {
+ "follows": true,
+ "content_type": "text/plain",
+ "length": 21
+ },
+ "bar.txt": {
+ "follows": true,
+ "content_type": "text/plain",
+ "length": 20
+ }
+ }
+ }
+
+ --abc123
+
+ this is 21 chars long
+ --abc123
+
+ this is 20 chars lon
+ --abc123--
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 72
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 09:13:24 GMT
+ ETag: "1-5575e26acdeb1df561bb5b70b26ba151"
+ Location: http://localhost:5984/temp/somedoc
+ Server: CouchDB (Erlang OTP)
+
+ {
+ "id": "somedoc",
+ "ok": true,
+ "rev": "1-5575e26acdeb1df561bb5b70b26ba151"
+ }
+
+
Getting a List of Revisions
---------------------------
[3/9] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 5522488
Posted by kx...@apache.org.
Stabilize order of HTTP API reference entries.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/8baf5eb0
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/8baf5eb0
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/8baf5eb0
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 8baf5eb03d57ed1cd15678a779b129d7ad696446
Parents: d282c82
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 10:04:47 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 10:04:47 2013 +0400
----------------------------------------------------------------------
share/doc/ext/httpdomain.py | 16 +++++++++++++++-
1 file changed, 15 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/8baf5eb0/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index a36493f..a2de686 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -201,6 +201,16 @@ http_sig_param_re = re.compile(r'\((?:(?P<type>[^:)]+):)?(?P<name>[\w_]+)\)',
re.VERBOSE)
+def sort_by_method(entries):
+ def cmp(item):
+ order = ['HEAD', 'GET', 'POST', 'PUT', 'DELETE', 'COPY', 'OPTIONS']
+ method = item[0].split(' ', 1)[0]
+ if method in order:
+ return order.index(method)
+ return 100
+ return sorted(entries, key=cmp)
+
+
def http_resource_anchor(method, path):
path = re.sub(r'[<>:/]', '-', path)
return method.lower() + '-' + path
@@ -455,7 +465,11 @@ class HTTPIndex(Index):
method.upper() + ' ' + path, 0, info[0],
http_resource_anchor(method, path), '', '', info[1]
])
- return (sorted(content.items()), True)
+ items = sorted(
+ (path, sort_by_method(entries))
+ for path, entries in content.items()
+ )
+ return (items, True)
class HTTPDomain(Domain):
[7/9] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 5522488
Posted by kx...@apache.org.
Describe POST /db/_changes and builtin filters.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/9a18fd22
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/9a18fd22
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/9a18fd22
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 9a18fd22e4e6ad11d255a1930dd686e48a288895
Parents: 5fe5893
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 12:11:10 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 12:11:10 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/changes.rst | 230 ++++++++++++++++++++++++++--
1 file changed, 213 insertions(+), 17 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/9a18fd22/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 52dc32d..f144f33 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -18,15 +18,13 @@
================
.. http:get:: /{db}/_changes
-.. http:head:: /{db}/_changes
-.. http:post:: /{db}/_changes
- A sorted list of changes made to documents in the database, in time order of
- application, can be obtained from the database's ``_changes`` resource. Only
- the most recent change for a given document is guaranteed to be provided,
- for example if a document has had fields added, and then deleted, an API
- client checking for changes will not necessarily receive the intermediate
- state of added documents.
+ 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``
+ resource. Only the most recent change for a given document is guaranteed to
+ be provided, for example if a document has had fields added, and then deleted,
+ an API client checking for changes will not necessarily receive the
+ intermediate state of added documents.
This can be used to listen for update and modifications to the database for
post processing or synchronization, and for practical purposes, a continuously
@@ -39,6 +37,10 @@
- :mimetype:`text/plain`
:<header Last-Event-ID: ID of the last events received by the server on a
previous connection. Overrides `since` query parameter.
+ :query array doc_ids: List of document IDs to filter the changes feed as
+ valid JSON array. Used with :ref:`_doc_ids <changes/filter/doc_ids>` filter.
+ Since `length of URL is limited`_, you better use :http:post:`/{db}/_changes`
+ method instead.
:query boolean conflicts: Includes `conflicts` information in response.
Ignored if `include_docs` isn't ``true``. Default is ``false``.
:query boolean descending: Return the change results in descending sequence
@@ -71,10 +73,9 @@
:ref:`changes_timeout <config/httpd/changes_timeout>` configuration option.
Note that ``60000`` value is also the default maximum timeout to prevent
undetected dead connections.
- :query string view: Allows to use view functions as filters. It requires to
- set ``filter`` special value ``_view`` to enable this feature.
- Documents counted as "passed" for view filter in case if map function emits
- at least one record for them.
+ :query string view: Allows to use view functions as filters. Documents
+ counted as "passed" for view filter in case if map function emits at least
+ one record for them. See :ref:`changes/filter/view` for more info.
:>header Cache-Control: ``no-cache`` if changes feed is
:ref:`eventsource <changes/eventsource>`
:>header Content-Type: - :mimetype:`application/json`
@@ -85,6 +86,7 @@
:>json number last_seq: Last change sequence number
:>json array results: Changes made to a database
:code 200: Request completed successfully
+ :code 400: Bad request
The ``result`` field of database changes
@@ -149,6 +151,7 @@
]
}
+.. _length of URL is limited: http://stackoverflow.com/a/417184/965635
.. versionchanged:: 0.11.0 added ``include_docs`` parameter
.. versionchanged:: 1.2.0 added ``view`` parameter and special value `_view`
@@ -159,6 +162,57 @@
.. versionchanged:: 1.4.0 Support ``Last-Event-ID`` header.
+.. http:post:: /{db}/_changes
+
+ Requests the database changes feed in the same way as
+ :http:get:`/{db}/_changes` does, but this method is widely used with
+ ``?filter=_doc_ids`` query parameter and allows to pass larger list of
+ document IDs to filter.
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /recipes/_changes?filter=_doc_ids HTTP/1.1
+ Accept: application/json
+ Content-Length: 40
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "doc_ids": [
+ "SpaghettiWithMeatballs"
+ ]
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 07:23:09 GMT
+ ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 38,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e"
+ }
+ ],
+ "id": "SpaghettiWithMeatballs",
+ "seq": 38
+ }
+ ]
+ }
+
+
.. _changes:
Changes Feeds
@@ -335,6 +389,8 @@ parameter.
.. _W3C eventsource specification: http://www.w3.org/TR/eventsource/
+.. _changes/filter:
+
Filtering
=========
@@ -348,13 +404,153 @@ You can also filter the ``_changes`` feed by defining a filter function
within a design document. The specification for the filter is the same
as for replication filters. You specify the name of the filter function
to the ``filter`` parameter, specifying the design document name and
-filter name. For example:
+:ref:`filter name <filterfun>`. For example:
.. code-block:: http
GET /db/_changes?filter=design_doc/filtername
-The ``_changes`` feed can be used to watch changes to specific document
-ID's or the list of ``_design`` documents in a database. If the
-``filters`` parameter is set to ``_doc_ids`` a list of doc IDs can be
-passed in the ``doc_ids`` parameter as a JSON array.
+Additionally, there are couple of builtin filters are available and described
+below.
+
+
+.. _changes/filter/doc_ids:
+
+_doc_ids
+--------
+
+This filter accepts only changes for documents which ID in specified in
+``doc_ids`` query parameter or payload's object array. See
+:http:post:`/{db}/_changes` for an example.
+
+
+.. _changes/filter/design:
+
+_design
+-------
+
+The ``_design`` filter accepts only changes for any design document within the
+requested database.
+
+**Request**:
+
+.. code-block:: http
+
+ GET /recipes/_changes?filter=_design HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 07:28:28 GMT
+ ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 38,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "10-304cae84fd862832ea9814f02920d4b2"
+ }
+ ],
+ "id": "_design/ingredients",
+ "seq": 29
+ },
+ {
+ "changes": [
+ {
+ "rev": "123-6f7c1b7c97a9e4f0d22bdf130e8fd817"
+ }
+ ],
+ "deleted": true,
+ "id": "_design/cookbook",
+ "seq": 35
+ },
+ {
+ "changes": [
+ {
+ "rev": "6-5b8a52c22580e922e792047cff3618f3"
+ }
+ ],
+ "deleted": true,
+ "id": "_design/meta",
+ "seq": 36
+ }
+ ]
+ }
+
+
+.. _changes/filter/view:
+
+_view
+-----
+
+.. versionadded:: 1.2
+
+The special filter ``_view`` allows to use existed :ref:`map function <mapfun>`
+as the :ref:`filter <filterfun>`. If the map function emits anything for the
+processed document he counts as accepted and the changes event emits to the
+feed. For most use-practice cases `filter` functions are very similar to `map`
+ones, so this feature helps to reduce amount of duplicated code.
+
+.. warning::
+
+ While :ref:`map functions <mapfun>` doesn't process the design documents,
+ using ``_view`` filter forces them to do this. You need to be sure, that
+ they are ready to handle documents with *alien* structure without panic
+ crush.
+
+.. note::
+
+ Using ``_view`` filter doesn't queries the view index files, so you cannot
+ use common :ref:`view query parameters <api/ddoc/view>` to additionally
+ filter the changes feed by index key. Also, CouchDB doesn't returns
+ the result instantly as he does for views - it really uses the specified
+ map function as filter.
+
+ Moreover, you cannot make such filters dynamic e.g. process the request
+ query parameters or handle the :ref:`userctx_object` - the map function is
+ only operates with the document.
+
+**Request**:
+
+.. code-block:: http
+
+ GET /recipes/_changes?filter=_view&view=ingredients/by_recipe HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 07:36:40 GMT
+ ETag: "ARIHFWL3I7PIS0SPVTFU6TLR2"
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 38,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "13-bcb9d6388b60fd1e960d9ec4e8e3f29e"
+ }
+ ],
+ "id": "SpaghettiWithMeatballs",
+ "seq": 38
+ }
+ ]
+ }
[2/9] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 5522488
Posted by kx...@apache.org.
Normalize API path's params names.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/d282c828
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/d282c828
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/d282c828
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: d282c828ab61b8822c0dfc27b370b32977ce0ccd
Parents: a00c6a4
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 09:22:21 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 09:22:21 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/ddoc/common.rst | 24 ++++++++++++------------
share/doc/src/api/ddoc/rewrites.rst | 4 ++--
share/doc/src/api/ddoc/views.rst | 12 ++++++------
share/doc/src/api/local.rst | 8 ++++----
4 files changed, 24 insertions(+), 24 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d282c828/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 1e5b183..79c7357 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -16,7 +16,7 @@
``/db/_design/design-doc``
==========================
-.. http:head:: /{db}/_design/{ddocname}
+.. http:head:: /{db}/_design/{ddoc}
Returns the HTTP Headers containing a minimal amount of information
about the specified design document.
@@ -26,7 +26,7 @@
:http:head:`/{db}/{docid}`
-.. http:get:: /{db}/_design/{ddocname}
+.. http:get:: /{db}/_design/{ddoc}
Returns design document with the specified design document` from the specified
database. Unless you request a specific revision, the latest revision of the
@@ -37,7 +37,7 @@
:http:get:`/{db}/{docid}`
-.. http:put:: /{db}/_design/{ddocname}
+.. http:put:: /{db}/_design/{ddoc}
The :http:method:`PUT` method creates a new named design document, or creates
a new revision of the existing design document.
@@ -67,7 +67,7 @@
:http:put:`/{db}/{docid}`
-.. http:delete:: /{db}/_design/{ddocname}
+.. http:delete:: /{db}/_design/{ddoc}
Deletes the specified document from the database. You must supply the
current (latest) revision, either by using the ``rev`` parameter to
@@ -77,7 +77,7 @@
:http:delete:`/{db}/{docid}`
-.. http:copy:: /{db}/_design/{ddocname}
+.. http:copy:: /{db}/_design/{ddoc}
The :http:method:`COPY` (which is non-standard HTTP) copies an existing
design document to a new or existing one.
@@ -97,7 +97,7 @@
``/db/_design/design-doc/attachment``
=====================================
-.. http:head:: /{db}/_design/{ddocname}/{attname}
+.. http:head:: /{db}/_design/{ddoc}/{attname}
Returns the HTTP headers containing a minimal amount of information
about the specified attachment.
@@ -106,7 +106,7 @@
:http:head:`/{db}/{docid}/{attname}`
-.. http:get:: /{db}/_design/{ddocname}/{attname}
+.. http:get:: /{db}/_design/{ddoc}/{attname}
Returns the file attachment associated with the design document.
The raw data of the associated attachment is returned (just as if you were
@@ -116,7 +116,7 @@
:http:get:`/{db}/{docid}/{attname}`
-.. http:put:: /{db}/_design/{ddocname}/{attname}
+.. http:put:: /{db}/_design/{ddoc}/{attname}
Uploads the supplied content as an attachment to the specified design
document. The attachment name provided must be a URL encoded string.
@@ -125,7 +125,7 @@
:http:put:`/{db}/{docid}/{attname}`
-.. http:delete:: /{db}/_design/{ddocname}/{attname}
+.. http:delete:: /{db}/_design/{ddoc}/{attname}
Deletes the attachment of the specified design document.
@@ -139,14 +139,14 @@
``/db/_design/design-doc/_info``
================================
-.. http:get:: /{db}/_design/{ddocname}/_info
+.. http:get:: /{db}/_design/{ddoc}/_info
Obtains information about the specified design document, including the index,
index size and current status of the design document and associated
index information.
:param db: Database name
- :param ddocname: Design document name
+ :param ddoc: Design document name
:<header Accept: - :mimetype:`application/json`
- :mimetype:`text/plain`
:>header Content-Type: - :mimetype:`application/json`
@@ -196,7 +196,7 @@
View Index Information
----------------------
-The response from :http:get:`/{db}/_design/{ddocname}/_info` contains
+The response from :http:get:`/{db}/_design/{ddoc}/_info` contains
``view_index`` (*object*) field with the next structure:
* **compact_running** (*boolean*): Indicates whether a compaction routine
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d282c828/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 3bcf6b4..61eebed 100644
--- a/share/doc/src/api/ddoc/rewrites.rst
+++ b/share/doc/src/api/ddoc/rewrites.rst
@@ -16,7 +16,7 @@
``/db/_design/design-doc/_rewrite/path``
========================================
-.. http:any:: /{db}/_design/{ddocname}/_rewrite/{path}
+.. http:any:: /{db}/_design/{ddoc}/_rewrite/{path}
Rewrites the specified path by rules defined in the specified design document.
@@ -85,5 +85,5 @@
are depended on endpoint to which url will be rewrited.
:param db: Database name
- :param ddocname: Design document name
+ :param ddoc: Design document name
:param path: URL path to rewrite
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d282c828/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 ade789c..7834539 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -16,13 +16,13 @@
``/db/_design/design-doc/_view/view-name``
==========================================
-.. http:get:: /{db}/_design/{ddocname}/_view/{viewname}
+.. http:get:: /{db}/_design/{ddoc}/_view/{view}
Executes the specified view function from the specified design document.
:param db: Database name
- :param ddocname: Design document name
- :param viewname: View function name
+ :param ddoc: Design document name
+ :param view: View function name
:<header Accept: - :mimetype:`application/json`
- :mimetype:`text/plain`
@@ -123,14 +123,14 @@
}
-.. http:post:: /{db}/_design/{ddocname}/_view/{viewname}
+.. http:post:: /{db}/_design/{ddoc}/_view/{view}
Executes the specified view function from the specified design document.
- Unlike the :http:get:`/{db}/_design/{ddocname}/_view/{viewname}` method
+ Unlike the :http:get:`/{db}/_design/{ddoc}/_view/{view}` method
for accessing views, the :http:method:`POST` method supports the specification
of explicit keys to be retrieved from the view results. The remainder of the
:http:method:`POST` view functionality is identical to the
- :http:get:`/{db}/_design/{ddocname}/_view/{viewname}` API.
+ :http:get:`/{db}/_design/{ddoc}/_view/{view}` API.
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d282c828/share/doc/src/api/local.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
index 83a64cf..0fb6d6c 100644
--- a/share/doc/src/api/local.rst
+++ b/share/doc/src/api/local.rst
@@ -55,25 +55,25 @@ A list of the available methods and URL paths are provided below:
``/db/_local/id``
========================
-.. http:get:: /{db}/_local/{id}
+.. http:get:: /{db}/_local/{docid}
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 :http:get:`/{db}/{docid}`.
-.. http:put:: /{db}/_local/{id}
+.. http:put:: /{db}/_local/{docid}
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 :http:put:`/{db}/{docid}`.
-.. http:delete:: /{db}/_local/{id}
+.. http:delete:: /{db}/_local/{docid}
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 :http:delete:`/{db}/{docid}`.
-.. http:copy:: /{db}/_local/{id}
+.. http:copy:: /{db}/_local/{docid}
Copies the specified local document. The semantics are identical to
copying a standard document in the specified database, except that the
[4/9] git commit: updated refs/heads/1781-reorganize-and-improve-docs
to 5522488
Posted by kx...@apache.org.
Provides short description for the HTTP API reference entries.
The description is defined within special JSON file instead of markup attributes.
There should be way to hack sphinx for this, but currently I don't know how to
do this. Hope this will be fixed in nearest future.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/088ea1ed
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/088ea1ed
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/088ea1ed
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 088ea1ed8c135647087fe99657cff07d714b9eb4
Parents: 8baf5eb
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 28 10:14:37 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Sat Sep 28 10:14:37 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +-
share/doc/ext/http-api-descr.json | 79 ++++++++++++++++++++++++++++++++++
share/doc/ext/httpdomain.py | 10 ++++-
3 files changed, 89 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/088ea1ed/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index d03eb30..5a9441f 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -414,7 +414,8 @@ src_files_html = \
sphinx_extensions = \
../ext/github.py \
- ../ext/httpdomain.py
+ ../ext/httpdomain.py \
+ ../ext/http-api-descr.json
EXTRA_DIST = \
$(image_files) \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/088ea1ed/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
new file mode 100644
index 0000000..e7672e4
--- /dev/null
+++ b/share/doc/ext/http-api-descr.json
@@ -0,0 +1,79 @@
+{
+ "GET /": "Returns the welcome message and version information",
+ "GET /_active_tasks": "Obtains a list of the tasks running in the server",
+ "GET /_all_dbs": "Returns a list of all the databases",
+ "GET /_config": "Obtains a list of the entire server configuration",
+ "GET /_config/{section}": "Returns all the configuration values for the specified section",
+ "DELETE /_config/{section}/{key}": "Removes the current setting",
+ "GET /_config/{section}/{key}": "Returns a specific section/configuration value",
+ "PUT /_config/{section}/{key}": "Sets the specified configuration value",
+ "GET /_db_updates": "Return the server changes of databases",
+ "GET /_log": "Returns the server log file",
+ "POST /_replicate": "Starts or cancels the replication",
+ "POST /_restart": "Restarts the server",
+ "DELETE /_session": "Logout Cookie-based user",
+ "GET /_session": "Returns Cookie-based login user information",
+ "POST /_session": "Authenticates user by Cookie-based user login",
+ "GET /_stats": "Returns server statistics",
+ "GET /_utils/": "CouchDB administration interface (Futon)",
+ "GET /_uuids": "Generates a list of UUIDs from the server",
+ "GET /favicon.ico": "Returns the site icon",
+ "DELETE /{db}": "Deletes an existing database",
+ "GET /{db}": "Returns the database information",
+ "HEAD /{db}": "Checks the database existence",
+ "POST /{db}": "Creates a new document with generic ID if he had not specified",
+ "PUT /{db}": "Creates a new database",
+ "GET /{db}/_all_docs": "Returns a built-in view of all documents in this database",
+ "POST /{db}/_all_docs": "Returns certain rows from the built-in view of all documents",
+ "POST /{db}/_bulk_docs": "Inserts or updates multiple documents in to the database in a single request",
+ "GET /{db}/_changes": "Returns changes for the given database",
+ "POST /{db}/_changes": "Returns changes for the given database for certain document IDs",
+ "POST /{db}/_compact": "Starts a compaction for the database",
+ "POST /{db}/_compact/{ddoc}": "Starts a compaction for all the views in the selected design document",
+ "COPY /{db}/_design/{ddoc}": "Copies the design document",
+ "DELETE /{db}/_design/{ddoc}": "Deletes the design document",
+ "GET /{db}/_design/{ddoc}": "Returns the design document",
+ "HEAD /{db}/_design/{ddoc}": "Returns bare information in the HTTP Headers for the design document",
+ "PUT /{db}/_design/{ddoc}": "Creates a new design document, or new version of an existing one",
+ "GET /{db}/_design/{ddoc}/_info": "Returns view index information for the specified design document",
+ "GET /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}": "Executes a list function against the view from other design document",
+ "POST /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}": "",
+ "GET /{db}/_design/{ddoc}/_list/{func}/{view}": "Executes a list function against the view from the same design document",
+ "POST /{db}/_design/{ddoc}/_list/{func}/{view}": "",
+ "ANY /{db}/_design/{ddoc}/_rewrite/{path}": "Rewrites HTTP request for the specified path by using stored routing rules",
+ "GET /{db}/_design/{ddoc}/_show/{func}": "Executes a show function against null document",
+ "POST /{db}/_design/{ddoc}/_show/{func}": "",
+ "GET /{db}/_design/{ddoc}/_show/{func}/{docid}": "Executes a show function against the specified document",
+ "POST /{db}/_design/{ddoc}/_show/{func}/{docid}": "",
+ "POST /{db}/_design/{ddoc}/_update/{func}": "Executes an update function",
+ "PUT /{db}/_design/{ddoc}/_update/{func}/{docid}": "Executes an update function against the specified document",
+ "GET /{db}/_design/{ddoc}/_view/{view}": "Returns results for the specified stored view",
+ "POST /{db}/_design/{ddoc}/_view/{view}": "Returns certain rows for the specified stored view",
+ "DELETE /{db}/_design/{ddoc}/{attname}": "Deletes an attachment of a design document",
+ "GET /{db}/_design/{ddoc}/{attname}": "Gets the attachment of a design document",
+ "HEAD /{db}/_design/{ddoc}/{attname}": "Returns bare information in the HTTP Headers for the attachment",
+ "PUT /{db}/_design/{ddoc}/{attname}": "Adds an attachment of a design document",
+ "POST /{db}/_ensure_full_commit": "Makes sure all uncommitted changes are written and synchronized to the disk",
+ "COPY /{db}/_local/{docid}": "Copies the non-replicated document",
+ "DELETE /{db}/_local/{docid}": "Deletes the non-replicated document",
+ "GET /{db}/_local/{docid}": "Returns the latest revision of the non-replicated document",
+ "PUT /{db}/_local/{docid}": "Inserts a new version of the non-replicated document",
+ "POST /{db}/_missing_revs": "By given list of document revisions, returns the document revisions that do not exist in the database",
+ "POST /{db}/_purge": "Purges some historical documents entirely from database history",
+ "POST /{db}/_revs_diff": "By given list of document revisions, returns differences between the given revisions and ones that are in the database",
+ "GET /{db}/_revs_limit": "Returns the limit of historical revisions to store for a single document in the database",
+ "PUT /{db}/_revs_limit": "Sets the limit of historical revisions to store for a single document in the database",
+ "GET /{db}/_security": "Returns the special security object for the database",
+ "PUT /{db}/_security": "Sets the special security object for the database",
+ "POST /{db}/_temp_view": "Executes a given view function for all documents and returns the result",
+ "POST /{db}/_view_cleanup": "Removes view files that are not used by any design document",
+ "COPY /{db}/{docid}": "Copies the document",
+ "DELETE /{db}/{docid}": "Deletes the document",
+ "GET /{db}/{docid}": "Returns the document",
+ "HEAD /{db}/{docid}": "Returns bare information in the HTTP Headers for the document",
+ "PUT /{db}/{docid}": "Creates a new document, or new version of an existing document",
+ "DELETE /{db}/{docid}/{attname}": "Deletes an attachment of a document",
+ "GET /{db}/{docid}/{attname}": "Gets the attachment of a document",
+ "HEAD /{db}/{docid}/{attname}": "Returns bare information in the HTTP Headers for the attachment",
+ "PUT /{db}/{docid}/{attname}": "Adds an attachment of a document"
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/couchdb/blob/088ea1ed/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index a2de686..afc81b5 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -9,6 +9,8 @@
"""
+import os
+import json
import re
from docutils import nodes
@@ -452,6 +454,8 @@ class HTTPIndex(Index):
name = 'api'
localname = 'HTTP API Reference'
shortname = 'API Reference'
+ api_descr = json.load(open(os.path.join(os.path.dirname(__file__),
+ 'http-api-descr.json')))
def generate(self, docnames=None):
content = {}
@@ -461,9 +465,11 @@ class HTTPIndex(Index):
items = sorted(items, key=lambda item: item[1])
for method, path, info in items:
entries = content.setdefault(path, [])
+ entry_name = method.upper() + ' ' + path
entries.append([
- method.upper() + ' ' + path, 0, info[0],
- http_resource_anchor(method, path), '', '', info[1]
+ entry_name, 0, info[0],
+ http_resource_anchor(method, path),
+ '', '', self.api_descr.get(entry_name, '')
])
items = sorted(
(path, sort_by_method(entries))