This is an automated email from the ASF dual-hosted git repository.
wohali pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
The following commit(s) were added to refs/heads/master by this push:
new 3aa2737 Last wiki migrations; rework of TOC & headers (#372)
3aa2737 is described below
commit 3aa2737f084a728fced4384740920b5069323d24
Author: Joan Touzet <woh...@users.noreply.github.com>
AuthorDate: Fri Dec 21 14:59:21 2018 -0500
Last wiki migrations; rework of TOC & headers (#372)
---
.travis.yml | 8 +++++++
ext/configdomain.py | 4 ++--
ext/httpdomain.py | 2 +-
src/api/local.rst | 5 ++---
src/cluster/index.rst | 6 +++---
src/conf.py | 6 ++++--
src/config/index.rst | 6 +++---
src/cve/index.rst | 6 +++---
src/ddocs/views/intro.rst | 14 ++++++++++++
src/ddocs/views/joins.rst | 29 ++++++++++++++-----------
src/index.rst | 48 +++++++++++++++++++++++++----------------
src/install/troubleshooting.rst | 18 ++++++++++++++++
src/intro/api.rst | 3 ++-
src/intro/overview.rst | 14 +++---------
src/maintenance/index.rst | 6 +++---
src/replication/conflicts.rst | 42 ++++++++++++++++++++++++++++++++++++
src/replication/index.rst | 2 +-
src/setup/cluster.rst | 8 +++----
src/whatsnew/index.rst | 7 +++---
templates/layout.html | 6 +++---
templates/pages/index.html | 4 ++--
21 files changed, 167 insertions(+), 77 deletions(-)
diff --git a/.travis.yml b/.travis.yml
index 5a3da42..7bfff38 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -2,6 +2,14 @@ language: python
python:
- 3.6
+# start a push build on master and release branches + PRs build on every branch
+# Avoid double build on PRs (See
https://github.com/travis-ci/travis-ci/issues/1147)
+branches:
+ only:
+ - master
+ - /^\d+\.x\.x$/
+ - /^\d+\.\d+\.x$/
+
install:
- pip install -r requirements.txt
diff --git a/ext/configdomain.py b/ext/configdomain.py
index fae52a9..66ed532 100644
--- a/ext/configdomain.py
+++ b/ext/configdomain.py
@@ -57,8 +57,8 @@ class ConfigObject(ObjectDescription):
class ConfigIndex(Index):
name = "ref"
- localname = "Configuration Reference"
- shortname = "Config Reference"
+ localname = "Configuration Quick Reference"
+ shortname = "Config Quick Reference"
def generate(self, docnames=None):
content = dict(
diff --git a/ext/httpdomain.py b/ext/httpdomain.py
index 6354b24..5e8803d 100644
--- a/ext/httpdomain.py
+++ b/ext/httpdomain.py
@@ -495,7 +495,7 @@ class HTTPXRefRole(XRefRole):
class HTTPIndex(Index):
name = "api"
- localname = "HTTP API Reference"
+ localname = "API Quick Reference"
shortname = "API Reference"
def generate(self, docnames=None):
diff --git a/src/api/local.rst b/src/api/local.rst
index c261721..0698ae2 100644
--- a/src/api/local.rst
+++ b/src/api/local.rst
@@ -54,9 +54,8 @@ A list of the available methods and URL paths are provided
below:
.. _api/local/doc:
-========================
``/db/_local_docs``
-========================
+===================
.. http:get:: /{db}/_local_docs
:synopsis: Returns a built-in view of all local (non-replicating) documents
@@ -227,7 +226,7 @@ A list of the available methods and URL paths are provided
below:
}
``/db/_local/id``
-========================
+=================
.. http:get:: /{db}/_local/{docid}
:synopsis: Returns the latest revision of the local document
diff --git a/src/cluster/index.rst b/src/cluster/index.rst
index 93973d0..46e569a 100644
--- a/src/cluster/index.rst
+++ b/src/cluster/index.rst
@@ -12,9 +12,9 @@
.. _cluster:
-=================
-Cluster Reference
-=================
+==================
+Cluster Management
+==================
As of CouchDB 2.0.0, CouchDB can be run in two different modes of operation:
* Standalone
diff --git a/src/conf.py b/src/conf.py
index 8ada770..a0cb15e 100644
--- a/src/conf.py
+++ b/src/conf.py
@@ -36,9 +36,11 @@ nitpicky = True
version = "2.3"
release = "2.3.0"
-project = "Apache CouchDB"
+project = u"Apache CouchDB\u00ae"
-copyright = "%d, %s" % (datetime.datetime.now().year, "Apache Software
Foundation")
+copyright = u"%d, %s" % (datetime.datetime.now().year, \
+ u"Apache Software Foundation. CouchDB\u00ae is a registered trademark
of the " + \
+ u"Apache Software Foundation")
primary_domain = "http"
diff --git a/src/config/index.rst b/src/config/index.rst
index 64b03bf..492f23d 100644
--- a/src/config/index.rst
+++ b/src/config/index.rst
@@ -12,9 +12,9 @@
.. _config:
-===================
-Configuring CouchDB
-===================
+=============
+Configuration
+=============
.. toctree::
:maxdepth: 2
diff --git a/src/cve/index.rst b/src/cve/index.rst
index d55fec8..8807d04 100644
--- a/src/cve/index.rst
+++ b/src/cve/index.rst
@@ -12,9 +12,9 @@
.. _cve:
-===========================
-Security Issues Information
-===========================
+======================
+Security Issues / CVEs
+======================
.. toctree::
:maxdepth: 1
diff --git a/src/ddocs/views/intro.rst b/src/ddocs/views/intro.rst
index 1596145..8ac6c82 100644
--- a/src/ddocs/views/intro.rst
+++ b/src/ddocs/views/intro.rst
@@ -178,6 +178,20 @@ confusion. CouchDB automatically includes the document ID
of the document that
created the entry in the view result. We’ll use this as well when constructing
links to the blog post pages.
+.. warning::
+
+ Do not emit the entire document as the value of your ``emit(key, value)``
+ statement unless you're sure you know you want it. This stores an entire
+ additional copy of your document in the view's secondary index. Views with
+ ``emit(key, doc)`` take longer to update, longer to write to disk, and
+ consume significantly more disk space. The only advantage is that they
+ are faster to query than using the ``?include_docs=true`` parameter when
+ querying a view.
+
+ Consider the trade-offs before emitting the entire document. Often it is
+ sufficient to emit only a portion of the document, or just a single key /
+ value pair, in your views.
+
Efficient Lookups
=================
diff --git a/src/ddocs/views/joins.rst b/src/ddocs/views/joins.rst
index d991fc5..df30078 100644
--- a/src/ddocs/views/joins.rst
+++ b/src/ddocs/views/joins.rst
@@ -334,9 +334,9 @@ some use of that:
function(doc) {
if (doc.type == "post") {
- emit([doc._id, 0], doc);
+ emit([doc._id, 0], null);
} else if (doc.type == "comment") {
- emit([doc.post, 1], doc);
+ emit([doc.post, 1], null);
}
}
@@ -349,7 +349,8 @@ and/or sort the results you get back from your views. When
you “invoke” a vi
you can say that you're only interested in a subset of the view rows by
specifying a ``?key=foo`` query string parameter. Or you can specify
``?startkey=foo`` and/or ``?endkey=bar`` query string parameters to fetch rows
-over a range of keys.
+over a range of keys. Finally, by adding ``?include_docs=true`` to the query,
+the result will include the full body of each emitted document.
It's also important to note that keys are always used for collating (i.e.
sorting) the rows. CouchDB has well defined (but as of yet undocumented) rules
@@ -380,23 +381,23 @@ the following:
"total_rows": 5, "offset": 0, "rows": [{
"id": "myslug",
"key": ["myslug", 0],
- "value": {...}
+ "value": null
}, {
"id": "ABCDEF",
"key": ["myslug", 1],
- "value": {...}
+ "value": null
}, {
"id": "DEFABC",
"key": ["myslug", 1],
- "value": {...}
+ "value": null
}, {
"id": "other_slug",
"key": ["other_slug", 0],
- "value": {...}
+ "value": null
}, {
"id": "CDEFAB",
"key": ["other_slug", 1],
- "value": {...}
+ "value": null
},
]
}
@@ -408,11 +409,12 @@ the following:
Now, to get a specific blog post and all associated comments, we'd invoke that
view with the query string::
- ?startkey=["myslug"]&endkey;=["myslug", 2]
+ ?startkey=["myslug"]&endkey=["myslug", 2]&include_docs=true
We'd get back the first three rows, those that belong to the ``myslug`` post,
-but not the others. Et voila, we now have the data we need to display a post
-with all associated comments, retrieved via a single ``GET`` request.
+but not the others, along with the full bodies of each document. Et voila, we
+now have the data we need to display a post with all associated comments,
+retrieved via a single ``GET`` request.
You may be asking what the 0 and 1 parts of the keys are for. They're simply
to ensure that the post document is always sorted before the the associated
@@ -424,5 +426,6 @@ One remaining problem with this model is that comments are
not ordered, but
that's simply because we don't have date/time information associated with them.
If we had, we'd add the timestamp as third element of the key array, probably
as ISO date/time strings. Now we would continue using the query string
-``?startkey=["myslug"]&endkey=["myslug", 2]`` to fetch the blog post and all
-associated comments, only now they'd be in chronological order.
+``?startkey=["myslug"]&endkey=["myslug", 2]&include_docs=true`` to fetch the
+blog post and all associated comments, only now they'd be in chronological
+order.
diff --git a/src/index.rst b/src/index.rst
index 03b1032..a592539 100644
--- a/src/index.rst
+++ b/src/index.rst
@@ -12,37 +12,47 @@
.. This file exists solely to hold the top-level Table of Contents.
-=============================================
-|Apache CouchDB(TM)|_ |release| Documentation
-=============================================
+==============
+Apache CouchDB
+==============
-Welcome! This is the documentation for Apache CouchDB |release|.
-
-Table of Contents
-=================
.. toctree::
+ :caption: User Guides
:maxdepth: 3
:numbered:
intro/index
+ replication/index
+ ddocs/index
+ best-practices/index
+
+.. toctree::
+ :caption: Administration Guides
+ :maxdepth: 3
+ :numbered:
+
install/index
setup/index
config/index
- replication/index
+ cluster/index
maintenance/index
- ddocs/index
- query-server/index
fauxton/index
- best-practices/index
+ experimental
+
+.. toctree::
+ :caption: Reference Guides
+ :maxdepth: 3
+ :numbered:
+
api/index
- cluster/index
json-structure
- experimental
- contributing
+ query-server/index
+
+.. toctree::
+ :caption: Other
+ :numbered:
+
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
-.. _Apache CouchDB(TM): http://couchdb.apache.org/
+ License <about>
+ contributing
diff --git a/src/install/troubleshooting.rst b/src/install/troubleshooting.rst
index acb5f8b..a2e9496 100644
--- a/src/install/troubleshooting.rst
+++ b/src/install/troubleshooting.rst
@@ -304,6 +304,24 @@ Because CouchDB does not make use of MD5 hashes for
cryptographic purposes, this
workaround does not defeat the purpose of "FIPS mode," provided that the system
owner is aware of and consents to its use.
+Debugging startup
+-----------------
+If you've compiled from scratch and are having problems getting CouchDB to even
+start up, you may want to see more detail. Start by enabling logging at the
debug
+level:
+
+.. code-block:: ini
+
+ [log]
+ level = debug
+
+You can then pass the ``-init_debug +W i +v +V -emu_args`` flags in the
``ERL_FLAGS``
+environment variable to turn on additional debugging information that CouchDB
+developers can use to help you.
+
+Then, reach out to the CouchDB development team using the links provided on the
+`CouchDB home page <https://couchdb.apache.org/>`_ for assistance.
+
macOS Known Issues
====================
undefined error, exit_status 134
diff --git a/src/intro/api.rst b/src/intro/api.rst
index 99731a5..82e067b 100644
--- a/src/intro/api.rst
+++ b/src/intro/api.rst
@@ -466,7 +466,8 @@ mechanisms, but we'll explore these later in the documents.
start learning one of the popular systems). Using new versions for document
changes works a lot like version control, but there's an important
difference: **CouchDB does not guarantee that older versions are kept
- around**.
+ around. Don't use the ``_rev`` token in CouchDB as a revision control
system
+ for your documents.**
Documents in Detail
-------------------
diff --git a/src/intro/overview.rst b/src/intro/overview.rst
index d9bd343..b58ce0e 100644
--- a/src/intro/overview.rst
+++ b/src/intro/overview.rst
@@ -37,7 +37,7 @@ editing the same document saves their changes first, the
client gets an edit
conflict error on save. To resolve the update conflict, the latest document
version can be opened, the edits reapplied and the update tried again.
-Document updates (add, edit, delete) are all or nothing, either succeeding
+Single document updates (add, edit, delete) are all or nothing, either
succeeding
entirely or failing completely. The database never contains partially saved
or edited documents.
@@ -59,7 +59,8 @@ reading documents without being locked out or interrupted by
concurrent
updates, even on the same document. CouchDB read operations use a
`Multi-Version Concurrency Control` (`MVCC`_) model where each client sees a
consistent snapshot of the database from the beginning to the end of the read
-operation.
+operation. This means that CouchDB can guarantee transactional semantics on
+a per-document basis.
Documents are indexed in `B-trees`_ by their name (DocID) and a Sequence ID.
Each update to a database instance generates a new sequential number.
@@ -318,15 +319,6 @@ histories. Updates to documents can be implemented to
exploit incremental
field and blob replication, where replicated updates are nearly as efficient
and incremental as the actual edit differences ("diffs").
-The CouchDB replication model can be modified for other distributed update
-models. If the storage engine is enhanced to allow multi-document update
-transactions, it is possible to perform Subversion-like "all or nothing"
-atomic commits when replicating with an upstream server, such that any single
-document conflict or validation failure will cause the entire update to fail.
-Like Subversion, conflicts would be resolved by doing a "pull" replication to
-force the conflicts locally, then merging and re-replicating to the upstream
-server.
-
Implementation
==============
diff --git a/src/maintenance/index.rst b/src/maintenance/index.rst
index ffb2f0d..449deff 100644
--- a/src/maintenance/index.rst
+++ b/src/maintenance/index.rst
@@ -10,9 +10,9 @@
.. License for the specific language governing permissions and limitations
under
.. the License.
-===================
-CouchDB Maintenance
-===================
+===========
+Maintenance
+===========
.. toctree::
diff --git a/src/replication/conflicts.rst b/src/replication/conflicts.rst
index 7b59cfa..2341fb9 100644
--- a/src/replication/conflicts.rst
+++ b/src/replication/conflicts.rst
@@ -258,6 +258,48 @@ delete.
Multiple document API
=====================
+Finding conflicted documents with Mango
+---------------------------------------
+
+.. versionadded:: 2.2.0
+
+CouchDB's :ref:`Mango system <api/db/_find>` allows easy querying of
+documents with conflicts, returning the full body of each document as well.
+
+Here's how to use it to find all conflicts in a database:
+
+.. code-block:: bash
+
+ $ curl -X POST http://127.0.0.1/dbname/_find \
+ -d '{"selector": {"_conflicts": { "$exists": true}}, "conflicts":
true}' \
+ -Hcontent-type:application/json
+
+.. code-block:: javascript
+
+ {"docs": [
+
{"_id":"doc","_rev":"1-3975759ccff3842adf690a5c10caee42","a":2,"_conflicts":["1-23202479633c2b380f79507a776743d5"]}
+ ],
+ "bookmark":
"g1AAAABheJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYozA1kgKQ6YVA5QkBFMgKSVDHWNjI0MjEzMLc2MjZONkowtDNLMLU0NzBPNzc3MTYxTTLOysgCY2ReV"}
+
+The ``bookmark`` value can be used to navigate through additional pages of
+results if necessary. Mango by default only returns 25 results per request.
+
+If you expect to run this query often, be sure to create a Mango secondary
+index to speed the query:
+
+.. code-block:: bash
+
+ $ curl -X POST http://127.0.0.1/dbname/_index \
+ -d '{"index":{"fields": ["_conflicts"]}}' \
+ -Hcontent-type:application/json
+
+Of course, the selector can be enhanced to filter documents on additional
+keys in the document. Be sure to add those keys to your secondary index as
+well, or a full database scan will be triggered.
+
+Finding conflicted documents using the ``_all_docs`` index
+----------------------------------------------------------
+
You can fetch multiple documents at once using ``include_docs=true`` on a view.
However, a ``conflicts=true`` request is ignored; the "doc" part of the value
never includes a ``_conflicts`` member. Hence you would need to do another
query
diff --git a/src/replication/index.rst b/src/replication/index.rst
index 4818ac8..6f79958 100644
--- a/src/replication/index.rst
+++ b/src/replication/index.rst
@@ -32,6 +32,6 @@ destination database.
:maxdepth: 2
intro
- protocol
replicator
conflicts
+ protocol
diff --git a/src/setup/cluster.rst b/src/setup/cluster.rst
index c40cbdf..ce80bc6 100644
--- a/src/setup/cluster.rst
+++ b/src/setup/cluster.rst
@@ -278,10 +278,10 @@ Now your cluster is ready and available! You can send
requests to any one of
the nodes, and all three will respond as if you are working with a single
CouchDB cluster.
-For a proper production setup, you'd now set up an HTTP proxy in front of the
-node that does load balancing and SSL termination, if desired. We recommend
-`HAProxy`_. See our `example configuration for HAProxy`_. All you need is to
-adjust the IP addresses or hostnames and ports.
+For a proper production setup, you'd now set up an HTTP reverse proxy in front
+of the cluster, for load balancing and SSL termination. We recommend
+`HAProxy`_, but others can be used. Sample configurations are available in the
+:ref:`best-practices` section.
.. _cluster/setup/api:
diff --git a/src/whatsnew/index.rst b/src/whatsnew/index.rst
index 3620588..4272b22 100644
--- a/src/whatsnew/index.rst
+++ b/src/whatsnew/index.rst
@@ -12,12 +12,13 @@
.. _releases:
-===============
-Release History
-===============
+=============
+Release Notes
+=============
.. toctree::
:glob:
+ :maxdepth: 2
2.3
2.2
diff --git a/templates/layout.html b/templates/layout.html
index 344950f..706e50f 100644
--- a/templates/layout.html
+++ b/templates/layout.html
@@ -15,10 +15,10 @@ specific language governing permissions and limitations
under the License.
{% block menu %}
<h2>Table of Contents</h2>
{{ super() }}
-<h2>Quick Reference</h2>
+<h2>Quick Reference Guides</h2>
<ul>
-<li><a href="{{ pathto('http-api') }}">HTTP API Reference</a></li>
-<li><a href="{{ pathto('config-ref') }}">Configuration Reference</a></li>
+<li><a href="{{ pathto('http-api') }}">API Quick Reference</a></li>
+<li><a href="{{ pathto('config-ref') }}">Configuration Quick Reference</a></li>
</ul>
{% if local %}
diff --git a/templates/pages/index.html b/templates/pages/index.html
index 3d032a0..4c26bfc 100644
--- a/templates/pages/index.html
+++ b/templates/pages/index.html
@@ -16,10 +16,10 @@ specific language governing permissions and limitations
under the License.
{% extends "layout.html" %}
{% set title = _('Overview') %}
{% block body %}
- <h1>{{ docstitle|e }}</h1>
+ <h1>Apache CouchDB<sup>®</sup> {{ release|e }} Documentation</h1>
<p>
{{ _('Welcome! This is') }}
- {% block description %}{{ _('the documentation for') }} {{ project|e }}
+ {% block description %}{{ _('the documentation for') }} Apache
CouchDB<sup>®</sup>
{{ release|e }}{% if last_updated %}, {{ _('last updated') }} {{
last_updated|e }}{% endif %}{% endblock %}.
</p>
{% block tables %}
