couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject [23/49] Move .rst files into Sphinx Layout
Date Fri, 14 Sep 2012 10:16:59 GMT
http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/api/misc.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/api/misc.rst b/share/docs/sphinx-docs/api/misc.rst
new file mode 100644
index 0000000..9a35030
--- /dev/null
+++ b/share/docs/sphinx-docs/api/misc.rst
@@ -0,0 +1,606 @@
+=====================
+Miscellaneous Methods
+=====================
+
+The CouchDB Miscellaneous interface provides the basic interface to a
+CouchDB server for obtaining CouchDB information and getting and setting
+configuration information.
+
+A list of the available methods and URL paths are provided below:
+
+Miscellaneous API Calls
+
+``GET /``
+=========
+
+Accessing the root of a CouchDB instance returns meta information about
+the instance. The response is a JSON structure containing information
+about the server, including a welcome message and the version of the
+server.
+
+::
+
+    {
+       "couchdb" : "Welcome",
+       "version" : "1.0.1"
+    }
+
+``GET /_active_tasks``
+======================
+
+You can obtain a list of active tasks by using the ``/_active_tasks``
+URL. The result is a JSON array of the currently running tasks, with
+each task being described with a single object. For example:
+
+::
+
+
+
+    [
+       {
+        "pid" : "<0.11599.0>",
+        "status" : "Copied 0 of 18369 changes (0%)",
+        "task" : "recipes",
+        "type" : "Database Compaction"
+        }
+    ]
+
+
+        
+
+The returned structure includes the following fields for each task:
+
+For operation type, valid values include:
+
+-  ``Database Compaction``
+
+-  ``Replication``
+
+-  ``View Group Compaction``
+
+-  ``View Group Indexer``
+
+``GET /_all_dbs``
+=================
+
+Returns a list of all the databases in the CouchDB instance. For
+example:
+
+::
+
+    GET http://couchdb:5984/_all_dbs
+    Accept: application/json
+
+The return is a JSON array:
+
+::
+
+    [
+       "_users",
+       "contacts",
+       "docs",
+       "invoices",
+       "locations"
+    ]
+
+``GET /_log``
+=============
+
+Gets the CouchDB log, equivalent to accessing the local log file of the
+corresponding CouchDB instance.
+
+When you request the log, the response is returned as plain (UTF-8)
+text, with an HTTP ``Content-type`` header as ``text/plain``.
+
+For example, the request:
+
+::
+
+    GET http://couchdb:5984/_log
+    Accept: */*
+
+The raw text is returned:
+
+::
+
+
+    [Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401
+
+    [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200
+
+    [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200
+
+    [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200
+
+    [Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200
+
+If you want to pick out specific parts of the log information you can
+use the ``bytes`` argument, which specifies the number of bytes to be
+returned, and ``offset``, which specifies where the reading of the log
+should start, counted back from the end. For example, if you use the
+following request:
+
+::
+
+    GET /_log?bytes=500&offset=2000
+
+Reading of the log will start at 2000 bytes from the end of the log, and
+500 bytes will be shown.
+
+``POST /_replicate``
+====================
+
+Request, configure, or stop, a replication operation.
+
+The specification of the replication request is controlled through the
+JSON content of the request. The JSON should be an object with the
+fields defining the source, target and other options. The fields of the
+JSON request are shown in the table below:
+
+Replication Operation
+---------------------
+
+The aim of the replication is that at the end of the process, all active
+documents on the source database are also in the destination database
+and all documents that were deleted in the source databases are also
+deleted (if they exist) on the destination database.
+
+Replication can be described as either push or pull replication:
+
+-  *Pull replication* is where the ``source`` is the remote CouchDB
+   instance, and the ``destination`` is the local database.
+
+   Pull replication is the most useful solution to use if your source
+   database has a permanent IP address, and your destination (local)
+   database may have a dynamically assigned IP address (for example,
+   through DHCP). This is particularly important if you are replicating
+   to a mobile or other device from a central server.
+
+-  *Push replication* is where the ``source`` is a local database, and
+   ``destination`` is a remote database.
+
+Specifying the Source and Target Database
+-----------------------------------------
+
+You must use the URL specification of the CouchDB database if you want
+to perform replication in either of the following two situations:
+
+-  Replication with a remote database (i.e. another instance of CouchDB
+   on the same host, or a different host)
+
+-  Replication with a database that requires authentication
+
+For example, to request replication between a database local to the
+CouchDB instance to which you send the request, and a remote database
+you might use the following request:
+
+::
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "source" : "recipes",
+       "target" : "http://coucdb-remote:5984/recipes",
+    }
+          
+
+In all cases, the requested databases in the ``source`` and ``target``
+specification must exist. If they do not, an error will be returned
+within the JSON object:
+
+::
+
+    {
+       "error" : "db_not_found"
+       "reason" : "could not open http://couchdb-remote:5984/ol1ka/",
+    }
+          
+
+You can create the target database (providing your user credentials
+allow it) by adding the ``create_target`` field to the request object:
+
+::
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "create_target" : true
+       "source" : "recipes",
+       "target" : "http://couchdb-remote:5984/recipes",
+    }
+
+The ``create_target`` field is not destructive. If the database already
+exists, the replication proceeds as normal.
+
+Single Replication
+------------------
+
+You can request replication of a database so that the two databases can
+be synchronized. By default, the replication process occurs one time and
+synchronizes the two databases together. For example, you can request a
+single synchronization between two databases by supplying the ``source``
+and ``target`` fields within the request JSON content.
+
+::
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "source" : "recipes",
+       "target" : "recipes-snapshot",
+    }
+
+In the above example, the databases ``recipes`` and ``recipes-snapshot``
+will be synchronized. These databases are local to the CouchDB instance
+where the request was made. The response will be a JSON structure
+containing the success (or failure) of the synchronization process, and
+statistics about the process:
+
+::
+
+    {
+       "ok" : true,
+       "history" : [
+          {
+             "docs_read" : 1000,
+             "session_id" : "52c2370f5027043d286daca4de247db0",
+             "recorded_seq" : 1000,
+             "end_last_seq" : 1000,
+             "doc_write_failures" : 0,
+             "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT",
+             "start_last_seq" : 0,
+             "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT",
+             "missing_checked" : 0,
+             "docs_written" : 1000,
+             "missing_found" : 1000
+          }
+       ],
+       "session_id" : "52c2370f5027043d286daca4de247db0",
+       "source_last_seq" : 1000
+    }
+
+The structure defines the replication status, as described in the table
+below:
+
+Continuous Replication
+----------------------
+
+Synchronization of a database with the previously noted methods happens
+only once, at the time the replicate request is made. To have the target
+database permanently replicated from the source, you must set the
+``continuous`` field of the JSON object within the request to true.
+
+With continuous replication changes in the source database are
+replicated to the target database in perpetuity until you specifically
+request that replication ceases.
+
+::
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "continuous" : true
+       "source" : "recipes",
+       "target" : "http://couchdb-remote:5984/recipes",
+    }
+
+Changes will be replicated between the two databases as long as a
+network connection is available between the two instances.
+
+    **Note**
+
+    Two keep two databases synchronized with each other, you need to set
+    replication in both directions; that is, you must replicate from
+    ``databasea`` to ``databaseb``, and separately from ``databaseb`` to
+    ``databasea``.
+
+Canceling Continuous Replication
+--------------------------------
+
+You can cancel continuous replication by adding the ``cancel`` field to
+the JSON request object and setting the value to true. Note that the
+structure of the request must be identical to the original for the
+cancelation request to be honoured. For example, if you requested
+continuous replication, the cancellation request must also contain the
+``continuous`` field.
+
+For example, the replication request:
+
+::
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+       "source" : "recipes",
+       "target" : "http://couchdb-remote:5984/recipes",
+       "create_target" : true,
+       "continuous" : true
+    }
+
+Must be canceled using the request:
+
+::
+
+    POST http://couchdb:5984/_replicate
+    Content-Type: application/json
+    Accept: application/json
+
+    {
+        "cancel" : true,
+        "continuous" : true
+        "create_target" : true,
+        "source" : "recipes",
+        "target" : "http://couchdb-remote:5984/recipes",
+    }
+
+Requesting cancellation of a replication that does not exist results in
+a 404 error.
+
+``POST /_restart``
+==================
+
+Restarts the CouchDB instance. You must be authenticated as a user with
+administration privileges for this to work.
+
+For example:
+
+::
+
+    POST http://admin:password@couchdb:5984/_restart
+
+The return value (if the server has not already restarted) is a JSON
+status object indicating that the request has been received:
+
+::
+
+    {
+       "ok" : true,
+    }
+
+If the server has already restarted, the header may be returned, but no
+actual data is contained in the response.
+
+``GET /_stats``
+===============
+
+The ``_stats`` method returns a JSON object containting the statistics
+for the running server. The object is structured with top-level sections
+collating the statistics for a range of entries, with each individual
+statistic being easily identified, and the content of each statistic is
+self-describing. For example, the request time statistics, within the
+``couchdb`` section are structured as follows:
+
+::
+
+    {
+       "couchdb" : {
+    ...
+          "request_time" : {
+             "stddev" : "27.509",
+             "min" : "0.333333333333333",
+             "max" : "152",
+             "current" : "400.976",
+             "mean" : "10.837",
+             "sum" : "400.976",
+             "description" : "length of a request inside CouchDB without MochiWeb"
+          },
+    ...
+        }
+    }
+          
+
+The fields provide the current, minimum and maximum, and a collection of
+statistical means and quantities. The quantity in each case is not
+defined, but the descriptions below provide
+
+The statistics are divided into the following top-level sections:
+
+-  ``couchdb``
+
+   Describes statistics specific to the internals of CouchDB.
+
+   +-------------------------+-------------------------------------------------------+----------------+
+   | Statistic ID            | Description                                           | Unit           |
+   +=========================+=======================================================+================+
+   | ``auth_cache_hits``     | Number of authentication cache hits                   | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``auth_cache_misses``   | Number of authentication cache misses                 | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``database_reads``      | Number of times a document was read from a database   | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``database_writes``     | Number of times a database was changed                | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``open_databases``      | Number of open databases                              | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``open_os_files``       | Number of file descriptors CouchDB has open           | number         |
+   +-------------------------+-------------------------------------------------------+----------------+
+   | ``request_time``        | Length of a request inside CouchDB without MochiWeb   | milliseconds   |
+   +-------------------------+-------------------------------------------------------+----------------+
+
+   Table: ``couchdb`` statistics
+
+-  ``httpd_request_methods``
+
+   +----------------+----------------------------------+----------+
+   | Statistic ID   | Description                      | Unit     |
+   +================+==================================+==========+
+   | ``COPY``       | Number of HTTP COPY requests     | number   |
+   +----------------+----------------------------------+----------+
+   | ``DELETE``     | Number of HTTP DELETE requests   | number   |
+   +----------------+----------------------------------+----------+
+   | ``GET``        | Number of HTTP GET requests      | number   |
+   +----------------+----------------------------------+----------+
+   | ``HEAD``       | Number of HTTP HEAD requests     | number   |
+   +----------------+----------------------------------+----------+
+   | ``POST``       | Number of HTTP POST requests     | number   |
+   +----------------+----------------------------------+----------+
+   | ``PUT``        | Number of HTTP PUT requests      | number   |
+   +----------------+----------------------------------+----------+
+
+   Table: ``httpd_request_methods`` statistics
+
+-  ``httpd_status_codes``
+
+   +----------------+------------------------------------------------------+----------+
+   | Statistic ID   | Description                                          | Unit     |
+   +================+======================================================+==========+
+   | ``200``        | Number of HTTP 200 OK responses                      | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``201``        | Number of HTTP 201 Created responses                 | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``202``        | Number of HTTP 202 Accepted responses                | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``301``        | Number of HTTP 301 Moved Permanently responses       | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``304``        | Number of HTTP 304 Not Modified responses            | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``400``        | Number of HTTP 400 Bad Request responses             | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``401``        | Number of HTTP 401 Unauthorized responses            | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``403``        | Number of HTTP 403 Forbidden responses               | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``404``        | Number of HTTP 404 Not Found responses               | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``405``        | Number of HTTP 405 Method Not Allowed responses      | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``409``        | Number of HTTP 409 Conflict responses                | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``412``        | Number of HTTP 412 Precondition Failed responses     | number   |
+   +----------------+------------------------------------------------------+----------+
+   | ``500``        | Number of HTTP 500 Internal Server Error responses   | number   |
+   +----------------+------------------------------------------------------+----------+
+
+   Table: ``httpd_status_codes`` statistics
+
+-  ``httpd``
+
+   +----------------------------------+----------------------------------------------+----------+
+   | Statistic ID                     | Description                                  | Unit     |
+   +==================================+==============================================+==========+
+   | ``bulk_requests``                | Number of bulk requests                      | number   |
+   +----------------------------------+----------------------------------------------+----------+
+   | ``clients_requesting_changes``   | Number of clients for continuous \_changes   | number   |
+   +----------------------------------+----------------------------------------------+----------+
+   | ``requests``                     | Number of HTTP requests                      | number   |
+   +----------------------------------+----------------------------------------------+----------+
+   | ``temporary_view_reads``         | Number of temporary view reads               | number   |
+   +----------------------------------+----------------------------------------------+----------+
+   | ``view_reads``                   | Number of view reads                         | number   |
+   +----------------------------------+----------------------------------------------+----------+
+
+   Table: ``httpd`` statistics
+
+You can also access individual statistics by quoting the statistics
+sections and statistic ID as part of the URL path. For example, to get
+the ``request_time`` statistics, you can use:
+
+::
+
+    GET /_stats/couchdb/request_time
+        
+
+This returns an entire statistics object, as with the full request, but
+containining only the request individual statistic. Hence, the returned
+structure is as follows:
+
+::
+
+    {
+       "couchdb" : {
+          "request_time" : {
+             "stddev" : 7454.305,
+             "min" : 1,
+             "max" : 34185,
+             "current" : 34697.803,
+             "mean" : 1652.276,
+             "sum" : 34697.803,
+             "description" : "length of a request inside CouchDB without MochiWeb"
+          }
+       }
+    }
+        
+
+``GET /_utils``
+===============
+
+Accesses the built-in Futon administration interface for CouchDB.
+
+``GET /_uuids``
+===============
+
+Requests one or more Universally Unique Identifiers (UUIDs) from the
+CouchDB instance. The response is a JSON object providing a list of
+UUIDs. For example:
+
+::
+
+    {
+       "uuids" : [
+          "7e4b5a14b22ec1cf8e58b9cdd0000da3"
+       ]
+    }
+
+You can use the ``count`` argument to specify the number of UUIDs to be
+returned. For example:
+
+::
+
+        GET http://couchdb:5984/_uuids?count=5
+
+Returns:
+
+::
+
+    {
+       "uuids" : [
+          "c9df0cdf4442f993fc5570225b405a80",
+          "c9df0cdf4442f993fc5570225b405bd2",
+          "c9df0cdf4442f993fc5570225b405e42",
+          "c9df0cdf4442f993fc5570225b4061a0",
+          "c9df0cdf4442f993fc5570225b406a20"
+       ]
+    }
+
+The UUID type is determined by the UUID type setting in the CouchDB
+configuration. See ?.
+
+For example, changing the UUID type to ``random``:
+
+::
+
+    PUT http://couchdb:5984/_config/uuids/algorithm
+    Content-Type: application/json
+    Accept: */*
+
+    "random"
+
+When obtaining a list of UUIDs:
+
+::
+
+    {
+       "uuids" : [
+          "031aad7b469956cf2826fcb2a9260492",
+          "6ec875e15e6b385120938df18ee8e496",
+          "cff9e881516483911aa2f0e98949092d",
+          "b89d37509d39dd712546f9510d4a9271",
+          "2e0dbf7f6c4ad716f21938a016e4e59f"
+       ]
+    }
+
+``GET /favicon.ico``
+====================
+
+Returns the site icon. The return ``Content-type`` header is
+``image/x-icon``, and the content stream is the image data.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/api/reference.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/api/reference.rst b/share/docs/sphinx-docs/api/reference.rst
new file mode 100644
index 0000000..0bbe2cb
--- /dev/null
+++ b/share/docs/sphinx-docs/api/reference.rst
@@ -0,0 +1,16 @@
+API Reference
+=============
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   configuration
+   authn
+   database
+   documents
+   design
+   misc
+   local
+   dbmaint

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/changes.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/changes.rst b/share/docs/sphinx-docs/changes.rst
new file mode 100644
index 0000000..29d31ec
--- /dev/null
+++ b/share/docs/sphinx-docs/changes.rst
@@ -0,0 +1,26 @@
+============
+Changes Feed
+============
+
+ 
+
+Polling
+=======
+
+ 
+
+Long Polling
+============
+
+ 
+
+Continuous
+==========
+
+ 
+
+Filters
+=======
+
+ 
+

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/conf.py
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/conf.py b/share/docs/sphinx-docs/conf.py
new file mode 100644
index 0000000..0db0ec7
--- /dev/null
+++ b/share/docs/sphinx-docs/conf.py
@@ -0,0 +1,242 @@
+# -*- coding: utf-8 -*-
+#
+# CouchDB documentation build configuration file, created by
+# sphinx-quickstart on Tue Jul 31 20:52:16 2012.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'CouchDB'
+copyright = u'2012, Developers'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.3.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.3.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'CouchDBdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'CouchDB.tex', u'CouchDB Documentation',
+   u'Developers', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'couchdb', u'CouchDB Documentation',
+     [u'Developers'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'CouchDB', u'CouchDB Documentation',
+   u'Developers', 'CouchDB', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/config.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/config.rst b/share/docs/sphinx-docs/config.rst
new file mode 100644
index 0000000..c67e608
--- /dev/null
+++ b/share/docs/sphinx-docs/config.rst
@@ -0,0 +1,105 @@
+=============================
+CouchDB Configuration Options
+=============================
+
+ 
+
+Configuration Groups
+
+``attachments`` Configuration Options
+=====================================
+
+ 
+
+Configuration Groups
+
+``couchdb`` Configuration Options
+=================================
+
+ 
+
+Configuration Groups
+
+``daemons`` Configuration Options
+=================================
+
+ 
+
+Configuration Groups
+
+``httpd_db_handlers`` Configuration Options
+===========================================
+
+ 
+
+Configuration Groups
+
+``couch_httpd_auth`` Configuration Options
+==========================================
+
+ 
+
+Configuration Groups
+
+``httpd`` Configuration Options
+===============================
+
+ 
+
+Configuration Groups
+
+``httpd_design_handlers`` Configuration Options
+===============================================
+
+ 
+
+Configuration Groups
+
+``httpd_global_handlers`` Configuration Options
+===============================================
+
+ 
+
+Configuration Groups
+
+``log`` Configuration Options
+=============================
+
+ 
+
+Configuration Groups
+
+``query_servers`` Configuration Options
+=======================================
+
+ 
+
+Configuration Groups
+
+``query_server_config`` Configuration Options
+=============================================
+
+ 
+
+Configuration Groups
+
+``replicator`` Configuration Options
+====================================
+
+ 
+
+Configuration Groups
+
+``stats`` Configuration Options
+===============================
+
+ 
+
+Configuration Groups
+
+``uuids`` Configuration Options
+===============================
+
+ 
+
+Configuration Groups

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/configuring.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/configuring.rst b/share/docs/sphinx-docs/configuring.rst
new file mode 100644
index 0000000..1f0059c
--- /dev/null
+++ b/share/docs/sphinx-docs/configuring.rst
@@ -0,0 +1,210 @@
+===================
+Configuring CouchDB
+===================
+
+ 
+
+CouchDB Configuration Files
+===========================
+
+ 
+
+Configuration File Locations
+============================
+
+CouchDB reads files from the following locations, in the following
+order.
+
+1. ``PREFIX/default.ini``
+
+2. ``PREFIX/default.d/*``
+
+3. ``PREFIX/local.ini``
+
+4. ``PREFIX/local.d/*``
+
+Settings in successive documents override the settings in earlier
+entries. For example, setting the ``bind_address`` parameter in
+``local.ini`` would override any setting in ``default.ini``.
+
+    **Warning**
+
+    The ``default.ini`` file may be overwritten during an upgrade or
+    re-installation, so localised changes should be made to the
+    ``local.ini`` file or files within the ``local.d`` directory.
+
+MochiWeb Server Options
+=======================
+
+Server options for the MochiWeb component of CouchDB can be added to the
+configuration files. Settings should be added to the ``server_options``
+option of the ``[httpd]`` section of ``local.ini``. For example:
+
+::
+
+    [httpd]
+    server_options = [{backlog, 128}, {acceptor_pool_size, 16}]
+           
+
+OS Daemons
+==========
+
+CouchDB now supports starting external processes. The support is simple
+and enables CouchDB to start each configured OS daemon. If the daemon
+stops at any point, CouchDB will restart it (with protection to ensure
+regularly failing daemons are not repeatedly restarted).
+
+The daemon starting process is one-to-one; for each each configured
+daemon in the configuration file, CouchDB will start exactly one
+instance. If you need to run multiple instances, then you must create
+separate individual configurations. Daemons are configured within the
+``[os_daemons]`` section of your configuration file (``local.ini``). The
+format of each configured daemon is:
+
+::
+
+    NAME = PATH ARGS
+        
+
+Where ``NAME`` is an arbitrary (and unique) name to identify the daemon;
+``PATH`` is the full path to the daemon to be executed; ``ARGS`` are any
+required arguments to the daemon.
+
+For example:
+
+::
+
+    [os_daemons]
+    basic_responder = /usr/local/bin/responsder.js
+
+There is no interactivity between CouchDB and the running process, but
+you can use the OS Daemons service to create new HTTP servers and
+responders and then use the new proxy service to redirect requests and
+output to the CouchDB managed service. For more information on proxying,
+see ?. For further background on the OS Daemon service, see `CouchDB
+Externals API`_
+
+Update Notifications
+====================
+
+ 
+
+Socket Options Configuration Setting
+====================================
+
+The socket options for the listening socket in CouchDB can now be set
+within the CouchDB configuration file. The setting should be added to
+the ``[httpd]`` section of the file using the option name
+``socket_options``. The specification is as a list of tuples. For
+example:
+
+::
+
+    [httpd]
+    socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]
+
+The options supported are a subset of full options supported by the
+TCP/IP stack. A list of the supported options are provided in the
+`Erlang inet`_ documentation.
+
+``vhosts`` definitions
+======================
+
+Similar to the rewrites section of a ``_design`` document, the
+``vhosts`` system uses variables in the form of :varname or wildcards in
+the form of asterisks. The variable results can be output into the
+resulting path as they are in the rewriter.
+
+Configuring SSL Network Sockets
+===============================
+
+SSL configuration in CouchDB was designed to be as easy as possible. All
+you need is two files; a certificate and a private key. If you bought an
+official SSL certificate from a certificate authority, both should be in
+your possession already.
+
+If you just want to try this out and don't want to pay anything upfront,
+you can create a self-signed certificate. Everything will work the same,
+but clients will get a warning about an insecure certificate.
+
+You will need the OpenSSL command line tool installed. It probably
+already is.
+
+::
+
+    shell> 
+    shell> 
+    shell> 
+    shell> 
+    mycert.pem privkey.pem
+
+Now, you need to edit CouchDB's configuration, either by editing your
+``local.ini`` file or using the ``/_config`` API calls or the
+configuration screen in Futon. Here is what you need to do in
+``local.ini``, you can infer what needs doing in the other places.
+
+Be sure to make these edits. Under ``[daemons]`` you should see:
+
+::
+
+    ; enable SSL support by uncommenting the following line and supply the PEM's below.
+    ; the default ssl port CouchDB listens on is 6984
+    ;httpsd = {couch_httpd, start_link, [https]}
+
+Here uncomment the last line:
+
+::
+
+    httpsd = {couch_httpd, start_link, [https]}
+
+Next, under ``[ssl]`` you will see:
+
+::
+
+    ;cert_file = /full/path/to/server_cert.pem
+    ;key_file = /full/path/to/server_key.pem
+
+Uncomment and adjust the paths so it matches your system's paths:
+
+::
+
+    cert_file = /home/jan/cert/mycert.pem
+    key_file = /home/jan/cert/privkey.pem
+
+For more information please read
+`http://www.openssl.org/docs/HOWTO/certificates.txt`_.
+
+Now start (or restart) CouchDB. You should be able to connect to it
+using HTTPS on port 6984:
+
+::
+
+    shell> 
+    curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
+    error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
+    More details here: http://curl.haxx.se/docs/sslcerts.html
+
+    curl performs SSL certificate verification by default, using a "bundle"
+    of Certificate Authority (CA) public keys (CA certs). If the default
+    bundle file isn't adequate, you can specify an alternate file
+    using the --cacert option.
+    If this HTTPS server uses a certificate signed by a CA represented in
+    the bundle, the certificate verification probably failed due to a
+    problem with the certificate (it might be expired, or the name might
+    not match the domain name in the URL).
+    If you'd like to turn off curl's verification of the certificate, use
+    the -k (or --insecure) option.
+
+Oh no what happened?! — Remember, clients will notify their users that
+your certificate is self signed. ``curl`` is the client in this case and
+it notifies you. Luckily you trust yourself (don't you?) and you can
+specify the ``-k`` option as the message reads:
+
+::
+
+    shell> 
+    {"couchdb":"Welcome","version":"1.1.0"}
+
+.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
+.. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2
+.. _`http://www.openssl.org/docs/HOWTO/certificates.txt`: http://www.openssl.org/docs/HOWTO/certificates.txt

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/errors.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/errors.rst b/share/docs/sphinx-docs/errors.rst
new file mode 100644
index 0000000..13f93a9
--- /dev/null
+++ b/share/docs/sphinx-docs/errors.rst
@@ -0,0 +1,26 @@
+==============
+Error Messages
+==============
+
+The errors reported when CouchDB is unable to read a required file have
+been updated so that explicit information about the files and problem
+can now be identified from the error message. The errors report file
+permission access either when reading or writing to configuration and
+database files.
+
+The error is raised both through the log file and the error message
+returned through the API call as a JSON error message. For example, when
+setting configuration values:
+
+::
+
+    shell> 
+    {"error":"file_permission_error","reason":"/etc/couchdb/local.ini"}
+        
+
+Errors will always be reported using the ``file_permission_error`` error
+type.
+
+During startup permissions errors on key files are also reported in the
+log with a descriptive error message and file location so that
+permissions can be fixed before restart.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/features.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/features.rst b/share/docs/sphinx-docs/features.rst
new file mode 100644
index 0000000..640407b
--- /dev/null
+++ b/share/docs/sphinx-docs/features.rst
@@ -0,0 +1,193 @@
+==========================
+Features and Functionality
+==========================
+
+ 
+
+HTTP Range Requests
+===================
+
+HTTP allows you to specify byte ranges for requests. This allows the
+implementation of resumable downloads and skippable audio and video
+streams alike. The following example uses a text file to make the range
+request process easier.
+
+::
+
+    shell> 
+    My hovercraft is full of eels!
+
+Uploading this as an attachment to a ``text`` database using ``curl``:
+
+::
+
+    shell> 
+    {"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}
+
+Requesting the whole file works as normal:
+
+::
+
+    shell> 
+    My hovercraft is full of eels!
+
+But to retrieve only the first 13 bytes using ``curl``:
+
+::
+
+    shell> 
+    My hovercraft
+
+HTTP supports many ways to specify single and even multiple byte
+rangers. See `RFC 2616`_.
+
+    **Note**
+
+    Databases that have been created with CouchDB 1.0.2 or earlier will
+    support range requests in 1.1.0, but they are using a less-optimal
+    algorithm. If you plan to make heavy use of this feature, make sure
+    to compact your database with CouchDB 1.1.0 to take advantage of a
+    better algorithm to find byte ranges.
+
+HTTP Proxying
+=============
+
+The HTTP proxy feature makes it easy to map and redirect different
+content through your CouchDB URL. The proxy works by mapping a pathname
+and passing all content after that prefix through to the configured
+proxy address.
+
+Configuration of the proxy redirect is handled through the
+``[httpd_global_handlers]`` section of the CouchDB configuration file
+(typically ``local.ini``). The format is:
+
+::
+
+    [httpd_global_handlers]
+    PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}
+      
+
+Where:
+
+-  ``PREFIX``
+
+   Is the string that will be matched. The string can be any valid
+   qualifier, although to ensure that existing database names are not
+   overridden by a proxy configuration, you can use an underscore
+   prefix.
+
+-  ``DESTINATION``
+
+   The fully-qualified URL to which the request should be sent. The
+   destination must include the ``http`` prefix. The content is used
+   verbatim in the original request, so you can also forward to servers
+   on different ports and to specific paths on the target host.
+
+The proxy process then translates requests of the form:
+
+::
+
+    http://couchdb:5984/PREFIX/path
+
+To:
+
+::
+
+    DESTINATION/path
+
+    **Note**
+
+    Everything after ``PREFIX`` including the required forward slash
+    will be appended to the ``DESTINATION``.
+
+The response is then communicated back to the original client.
+
+For example, the following configuration:
+
+::
+
+
+    _google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}
+
+Would forward all requests for ``http://couchdb:5984/_google`` to the
+Google website.
+
+The service can also be used to forward to related CouchDB services,
+such as Lucene:
+
+::
+
+      
+    [httpd_global_handlers]
+    _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}
+
+    **Note**
+
+    The proxy service is basic. If the request is not identified by the
+    ``DESTINATION``, or the remainder of the ``PATH`` specification is
+    incomplete, the original request URL is interpreted as if the
+    ``PREFIX`` component of that URL does not exist.
+
+    For example, requesting ``http://couchdb:5984/_intranet/media`` when
+    ``/media`` on the proxy destination does not exist, will cause the
+    request URL to be interpreted as ``http://couchdb:5984/media``. Care
+    should be taken to ensure that both requested URLs and destination
+    URLs are able to cope
+
+CommonJS support for map functions
+==================================
+
+CommonJS support allows you to use CommonJS notation inside map and
+reduce functions, but only of libraries that are stored inside the views
+part of the design doc.
+
+So you could continue to access CommonJS code in design\_doc.foo, from
+your list functions etc, but we'd add the ability to require CommonJS
+modules within map and reduce, but only from ``design_doc.views.lib``.
+
+There's no worry here about namespace collisions, as Couch just plucks
+``views.*.map`` and ``views.*.reduce`` out of the design doc. So you
+could have a view called ``lib`` if you wanted, and still have CommonJS
+stored in ``views.lib.sha1`` and ``views.lib.stemmer`` if you wanted.
+
+The implementation is simplified by enforcing that CommonJS modules to
+be used in map functions be stored in views.lib.
+
+A sample design doc (taken from the test suite in Futon) is below:
+
+::
+
+    {
+       "views" : {
+          "lib" : {
+             "baz" : "exports.baz = 'bam';",
+             "foo" : {
+                "zoom" : "exports.zoom = 'yeah';",
+                "boom" : "exports.boom = 'ok';",
+                "foo" : "exports.foo = 'bar';"
+             }
+          },
+          "commonjs" : {
+             "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}"
+          }
+       },
+       "_id" : "_design/test"
+    }
+
+The ``require()`` statement is relative to the design document, but
+anything loaded form outside of ``views/lib`` will fail.
+
+Granular ETag support
+=====================
+
+ETags have been assigned to a map/reduce group (the collection of views
+in a single design document). Any change to any of the indexes for those
+views would generate a new ETag for all view URL's in a single design
+doc, even if that specific view's results had not changed.
+
+In CouchDB 1.1 each ``_view`` URL has it's own ETag which only gets
+updated when changes are made to the database that effect that index. If
+the index for that specific view does not change, that view keeps the
+original ETag head (therefore sending back 304 Not Modified more often).
+
+.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/images/futon-createdb.png
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/images/futon-createdb.png b/share/docs/sphinx-docs/images/futon-createdb.png
new file mode 100644
index 0000000..c8c1b9d
Binary files /dev/null and b/share/docs/sphinx-docs/images/futon-createdb.png differ

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/images/futon-editdoc.png
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/images/futon-editdoc.png b/share/docs/sphinx-docs/images/futon-editdoc.png
new file mode 100644
index 0000000..6802c2c
Binary files /dev/null and b/share/docs/sphinx-docs/images/futon-editdoc.png differ

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/images/futon-editeddoc.png
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/images/futon-editeddoc.png b/share/docs/sphinx-docs/images/futon-editeddoc.png
new file mode 100644
index 0000000..5c8b549
Binary files /dev/null and b/share/docs/sphinx-docs/images/futon-editeddoc.png differ

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/images/futon-overview.png
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/images/futon-overview.png b/share/docs/sphinx-docs/images/futon-overview.png
new file mode 100644
index 0000000..d1eac6e
Binary files /dev/null and b/share/docs/sphinx-docs/images/futon-overview.png differ

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/images/futon-replform.png
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/images/futon-replform.png b/share/docs/sphinx-docs/images/futon-replform.png
new file mode 100644
index 0000000..d904f0d
Binary files /dev/null and b/share/docs/sphinx-docs/images/futon-replform.png differ

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/index.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/index.rst b/share/docs/sphinx-docs/index.rst
new file mode 100644
index 0000000..cf6abec
--- /dev/null
+++ b/share/docs/sphinx-docs/index.rst
@@ -0,0 +1,32 @@
+.. CouchDB documentation master file, created by
+   sphinx-quickstart on Tue Jul 31 20:52:16 2012.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to CouchDB's documentation!
+===================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   features
+   replication
+   errors
+   views
+   configuring
+   api
+   changes
+   config
+   api/reference
+   1.1/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/intro.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/intro.rst b/share/docs/sphinx-docs/intro.rst
new file mode 100644
index 0000000..ea59cf1
--- /dev/null
+++ b/share/docs/sphinx-docs/intro.rst
@@ -0,0 +1,285 @@
+============
+Introduction
+============
+
+There are two interfaces to CouchDB, the built-in Futon web-based
+interface and the CouchDB API accessed through the HTTP REST interface.
+The former is the simplest way to view and monitor your CouchDB
+installation and perform a number of basic database and system
+operations. More information on using the Futon interface can be found
+in ?.
+
+The primary way to interact with the CouchDB API is to use a client
+library or other interface that provides access to the underlying
+functionality through your chosen language or platform. However, since
+the API is supported through HTTP REST, you can interact with your
+CouchDB with any solution that supports the HTTP protocol.
+
+There are a number of different tools that talk the HTTP protocol and
+allow you to set and configure the necessary information. One tool for
+this that allows for access from the command-line is ``curl``. See ?.
+
+Using Futon
+===========
+
+Futon is a native web-based interface built into CouchDB. It provides a
+basic interface to the majority of the functionality, including the
+ability to create, update, delete and view documents and views, provides
+access to the configuration parameters, and an interface for initiating
+replication.
+
+The default view is the Overview page which provides you with a list of
+the databases. The basic structure of the page is consistent regardless
+of the section you are in. The main panel on the left provides the main
+interface to the databases, configuration or replication systems. The
+side panel on the right provides navigation to the main areas of Futon
+interface:
+
+.. figure:: images/futon-overview.png
+   :align: center
+   :alt:  Futon Overview
+
+    Futon Overview
+The main sections are:
+
+-  Overview
+
+   The main overview page, which provides a list of the databases and
+   provides the interface for querying the database and creating and
+   updating documents. See ?.
+
+-  Configuration
+
+   An interface into the configuration of your CouchDB installation. The
+   interface allows you to edit the different configurable parameters.
+   For more details on configuration, see ?.
+
+-  Replicator
+
+   An interface to the replication system, enabling you to initiate
+   replication between local and remote databases. See ?.
+
+-  Status
+
+   Displays a list of the running background tasks on the server.
+   Background tasks include view index building, compaction and
+   replication. The Status page is an interface to the `Active Tasks`_
+   API call. See ?.
+
+-  Verify Installation
+
+   The Verify Installation allows you to check whether all of the
+   components of your CouchDB installation are correctly installed.
+
+-  Test Suite
+
+   The Test Suite section allows you to run the built-in test suite.
+   This executes a number of test routines entirely within your browser
+   to test the API and functionality of your CouchDB installation. If
+   you select this page, you can run the tests by using the Run All
+   button. This will execute all the tests, which may take some time.
+
+Managing Databases and Documents
+--------------------------------
+
+You can manage databases and documents within Futon using the main
+Overview section of the Futon interface.
+
+To create a new database, click the Create Database ELLIPSIS button. You
+will be prompted for the database name, as shown in the figure below.
+
+.. figure:: images/futon-createdb.png
+   :align: center
+   :alt:  Creating a Database
+
+    Creating a Database
+Once you have created the database (or selected an existing one), you
+will be shown a list of the current documents. If you create a new
+document, or select an existing document, you will be presented with the
+edit document display.
+
+Editing documents within Futon requires selecting the document and then
+editing (and setting) the fields for the document individually before
+saving the document back into the database.
+
+For example, the figure below shows the editor for a single document, a
+newly created document with a single ID, the document ``_id`` field.
+
+.. figure:: images/futon-editdoc.png
+   :align: center
+   :alt:  Editing a Document
+
+    Editing a Document
+To add a field to the document:
+
+1. Click Add Field.
+
+2. In the fieldname box, enter the name of the field you want to create.
+   For example, “company”.
+
+3. Click the green tick next to the field name to confirm the field name
+   change.
+
+4. Double-click the corresponding Value cell.
+
+5. Enter a company name, for example “Example”.
+
+6. Click the green tick next to the field value to confirm the field
+   value.
+
+7. The document is still not saved as this point. You must explicitly
+   save the document by clicking the Save Document button at the top of
+   the page. This will save the document, and then display the new
+   document with the saved revision information (the ``_rev`` field).
+
+   .. figure:: images/futon-editeddoc.png
+      :align: center
+      :alt:  Edited Document
+
+       Edited Document
+
+The same basic interface is used for all editng operations within Futon.
+You *must* rememmbr to save the individual element (fieldname, value)
+using the green tick button, before then saving the document.
+
+Configuring Replication
+-----------------------
+
+When you click the Replicator option within the Tools menu you are
+presented with the Replicator screen. This allows you to start
+replication between two databases by filling in or select the
+appropriate options within the form provided.
+
+.. figure:: images/futon-replform.png
+   :align: center
+   :alt:  Replication Form
+
+    Replication Form
+To start a replication process, either the select the local database or
+enter a remote database name into the corresponding areas of the form.
+Replication occurs from the database on the left to the database on the
+right.
+
+If you are specifying a remote database name, you must specify the full
+URL of the remote database (including the host, port number and database
+name). If the remote instance requires authentication, you can specify
+the username and password as part of the URL, for example
+``http://username:pass@remotehost:5984/demo``.
+
+To enable continuous replication, click the Continuous checkbox.
+
+To start the replication process, click the Replicate button. The
+replication process should start and will continue in the background. If
+the replication process will take a long time, you can monitor the
+status of the replication using the Status option under the Tools menu.
+
+Once replication has been completed, the page will show the information
+returned when the replication process completes by the API.
+
+The Replicator tool is an interface to the underlying replication API.
+For more information, see ?. For more information on replication, see ?.
+
+Using ``curl``
+==============
+
+The ``curl`` utility is a command line tool available on Unix, Linux,
+Mac OS X and Windows and many other platforms. ``curl`` provides easy
+access to the HTTP protocol (among others) directly from the
+command-line and is therefore an ideal way of interacting with CouchDB
+over the HTTP REST API.
+
+For simple ``GET`` requests you can supply the URL of the request. For
+example, to get the database information:
+
+::
+
+    shell> 
+
+This returns the database information (formatted in the output below for
+clarity):
+
+::
+
+    {
+       "modules" : {
+          "geocouch" : "7fd793c10f3aa667a1088a937398bc5b51472b7f"
+       },
+       "couchdb" : "Welcome",
+       "version" : "1.1.0",
+    }
+
+    **Note**
+
+    For some URLs, especially those that include special characters such
+    as ampersand, exclamation mark, or question mark, you should quote
+    the URL you are specifying on the command line. For example:
+
+    ::
+
+        shell> 
+
+You can explicitly set the HTTP command using the ``-X`` command line
+option. For example, when creating a database, you set the name of the
+database in the URL you send using a PUT request:
+
+::
+
+    shell> 
+    {"ok":true}
+
+But to obtain the database information you use a ``GET`` request (with
+the return information formatted for clarity):
+
+::
+
+    shell> 
+    {
+       "compact_running" : false,
+       "doc_count" : 0,
+       "db_name" : "demo",
+       "purge_seq" : 0,
+       "committed_update_seq" : 0,
+       "doc_del_count" : 0,
+       "disk_format_version" : 5,
+       "update_seq" : 0,
+       "instance_start_time" : "1306421773496000",
+       "disk_size" : 79
+    }
+
+For certain operations, you must specify the content type of request,
+which you do by specifying the ``Content-Type`` header using the ``-H``
+command-line option:
+
+::
+
+    shell> 
+
+You can also submit 'payload' data, that is, data in the body of the
+HTTP request using the ``-d`` option. This is useful if you need to
+submit JSON structures, for example document data, as part of the
+request. For example, to submit a simple document to the ``demo``
+database:
+
+::
+
+    shell> 
+    {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
+     "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}
+
+In the above example, the argument after the ``-d`` option is the JSON
+of the document we want to submit.
+
+The document can be accessed by using the automatically generated
+document ID that was returned:
+
+::
+
+    shell> 
+    {"_id":"8843faaf0b831d364278331bc3001bd8",
+     "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
+     "company":"Example, Inc."}
+
+The API samples in the ? show the HTTP command, URL and any payload
+information that needs to be submitted (and the expected return value).
+All of these examples can be reproduced using ``curl`` with the
+command-line examples shown above.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/make.bat
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/make.bat b/share/docs/sphinx-docs/make.bat
new file mode 100644
index 0000000..4994199
--- /dev/null
+++ b/share/docs/sphinx-docs/make.bat
@@ -0,0 +1,190 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+set I18NSPHINXOPTS=%SPHINXOPTS% source
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\CouchDB.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\CouchDB.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/replication.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/replication.rst b/share/docs/sphinx-docs/replication.rst
new file mode 100644
index 0000000..9fadc6e
--- /dev/null
+++ b/share/docs/sphinx-docs/replication.rst
@@ -0,0 +1,371 @@
+===========
+Replication
+===========
+
+Replicator Database
+-------------------
+
+A database where you ``PUT``/``POST`` documents to trigger replications
+and you ``DELETE`` to cancel ongoing replications. These documents have
+exactly the same content as the JSON objects we used to ``POST`` to
+``_replicate`` (fields ``source``, ``target``, ``create_target``,
+``continuous``, ``doc_ids``, ``filter``, ``query_params``.
+
+Replication documents can have a user defined ``_id``. Design documents
+(and ``_local`` documents) added to the replicator database are ignored.
+
+The default name of this database is ``_replicator``. The name can be
+changed in the ``local.ini`` configuration, section ``[replicator]``,
+parameter ``db``.
+
+Basics
+~~~~~~
+
+Let's say you PUT the following document into \_replicator:
+
+::
+
+    {
+        "_id": "my_rep",
+        "source":  "http://myserver.com:5984/foo",
+        "target":  "bar",
+        "create_target":  true
+    }
+
+In the couch log you'll see 2 entries like these:
+
+::
+
+    [Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target`
+    [Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`)
+
+As soon as the replication is triggered, the document will be updated by
+CouchDB with 3 new fields:
+
+::
+
+    {
+        "_id": "my_rep",
+        "source":  "http://myserver.com:5984/foo",
+        "target":  "bar",
+        "create_target":  true,
+        "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+        "_replication_state":  "triggered",
+        "_replication_state_time":  1297974122
+    }
+
+Special fields set by the replicator start with the prefix
+``_replication_``.
+
+-  ``_replication_id``
+
+   The ID internally assigned to the replication. This is also the ID
+   exposed by ``/_active_tasks``.
+
+-  ``_replication_state``
+
+   The current state of the replication.
+
+-  ``_replication_state_time``
+
+   A Unix timestamp (number of seconds since 1 Jan 1970) that tells us
+   when the current replication state (marked in ``_replication_state``)
+   was set.
+
+When the replication finishes, it will update the ``_replication_state``
+field (and ``_replication_state_time``) with the value ``completed``, so
+the document will look like:
+
+::
+
+    {
+        "_id": "my_rep",
+        "source":  "http://myserver.com:5984/foo",
+        "target":  "bar",
+        "create_target":  true,
+        "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+        "_replication_state":  "completed",
+        "_replication_state_time":  1297974122
+    }
+
+When an error happens during replication, the ``_replication_state``
+field is set to ``error`` (and ``_replication_state`` gets updated of
+course).
+
+When you PUT/POST a document to the ``_replicator`` database, CouchDB
+will attempt to start the replication up to 10 times (configurable under
+``[replicator]``, parameter ``max_replication_retry_count``). If it
+fails on the first attempt, it waits 5 seconds before doing a second
+attempt. If the second attempt fails, it waits 10 seconds before doing a
+third attempt. If the third attempt fails, it waits 20 seconds before
+doing a fourth attempt (each attempt doubles the previous wait period).
+When an attempt fails, the Couch log will show you something like:
+
+::
+
+    [error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">>
+
+    **Note**
+
+    The ``_replication_state`` field is only set to ``error`` when all
+    the attempts were unsuccessful.
+
+There are only 3 possible values for the ``_replication_state`` field:
+``triggered``, ``completed`` and ``error``. Continuous replications
+never get their state set to ``completed``.
+
+Documents describing the same replication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Lets suppose 2 documents are added to the ``_replicator`` database in
+the following order:
+
+::
+
+    {
+        "_id": "doc_A",
+        "source":  "http://myserver.com:5984/foo",
+        "target":  "bar"
+    }
+
+and
+
+::
+
+    {
+        "_id": "doc_B",
+        "source":  "http://myserver.com:5984/foo",
+        "target":  "bar"
+    }
+
+Both describe exactly the same replication (only their ``_ids`` differ).
+In this case document ``doc_A`` triggers the replication, getting
+updated by CouchDB with the fields ``_replication_state``,
+``_replication_state_time`` and ``_replication_id``, just like it was
+described before. Document ``doc_B`` however, is only updated with one
+field, the ``_replication_id`` so it will look like this:
+
+::
+
+    {
+        "_id": "doc_B",
+        "source":  "http://myserver.com:5984/foo",
+        "target":  "bar",
+        "_replication_id":  "c0ebe9256695ff083347cbf95f93e280"
+    }
+
+While document ``doc_A`` will look like this:
+
+::
+
+    {
+        "_id": "doc_A",
+        "source":  "http://myserver.com:5984/foo",
+        "target":  "bar",
+        "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+        "_replication_state":  "triggered",
+        "_replication_state_time":  1297974122
+    }
+
+Note that both document get exactly the same value for the
+``_replication_id`` field. This way you can identify which documents
+refer to the same replication - you can for example define a view which
+maps replication IDs to document IDs.
+
+Canceling replications
+~~~~~~~~~~~~~~~~~~~~~~
+
+To cancel a replication simply ``DELETE`` the document which triggered
+the replication. The Couch log will show you an entry like the
+following:
+
+::
+
+    [Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted
+
+    **Note**
+
+    You need to ``DELETE`` the document that triggered the replication.
+    ``DELETE``\ ing another document that describes the same replication
+    but did not trigger it, will not cancel the replication.
+
+Server restart
+~~~~~~~~~~~~~~
+
+When CouchDB is restarted, it checks its ``_replicator`` database and
+restarts any replication that is described by a document that either has
+its ``_replication_state`` field set to ``triggered`` or it doesn't have
+yet the ``_replication_state`` field set.
+
+    **Note**
+
+    Continuous replications always have a ``_replication_state`` field
+    with the value ``triggered``, therefore they're always restarted
+    when CouchDB is restarted.
+
+Changing the Replicator Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Imagine your replicator database (default name is \_replicator) has the
+two following documents that represent pull replications from servers A
+and B:
+
+::
+
+    {
+        "_id": "rep_from_A",
+        "source":  "http://aserver.com:5984/foo",
+        "target":  "foo_a",
+        "continuous":  true,
+        "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+        "_replication_state":  "triggered",
+        "_replication_state_time":  1297971311
+    }
+    {
+        "_id": "rep_from_B",
+        "source":  "http://bserver.com:5984/foo",
+        "target":  "foo_b",
+        "continuous":  true,
+        "_replication_id":  "231bb3cf9d48314eaa8d48a9170570d1",
+        "_replication_state":  "triggered",
+        "_replication_state_time":  1297974122
+    }
+
+Now without stopping and restarting CouchDB, you change the name of the
+replicator database to ``another_replicator_db``:
+
+::
+
+    $ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"'
+    "_replicator"
+
+As soon as this is done, both pull replications defined before, are
+stopped. This is explicitly mentioned in CouchDB's log:
+
+::
+
+    [Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed
+    [Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200
+
+Imagine now you add a replication document to the new replicator
+database named ``another_replicator_db``:
+
+::
+
+    {
+        "_id": "rep_from_X",
+        "source":  "http://xserver.com:5984/foo",
+        "target":  "foo_x",
+        "continuous":  true
+    }
+
+From now own you have a single replication going on in your system: a
+pull replication pulling from server X. Now you change back the
+replicator database to the original one ``_replicator``:
+
+::
+
+    $ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"'
+    "another_replicator_db"
+
+Immediately after this operation, the replication pulling from server X
+will be stopped and the replications defined in the \_replicator
+database (pulling from servers A and B) will be resumed.
+
+Changing again the replicator database to ``another_replicator_db`` will
+stop the pull replications pulling from servers A and B, and resume the
+pull replication pulling from server X.
+
+Replicating the replicator database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Imagine you have in server C a replicator database with the two
+following pull replication documents in it:
+
+::
+
+    {
+         "_id": "rep_from_A",
+         "source":  "http://aserver.com:5984/foo",
+         "target":  "foo_a",
+         "continuous":  true,
+         "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+         "_replication_state":  "triggered",
+         "_replication_state_time":  1297971311
+    }
+    {
+         "_id": "rep_from_B",
+         "source":  "http://bserver.com:5984/foo",
+         "target":  "foo_b",
+         "continuous":  true,
+         "_replication_id":  "231bb3cf9d48314eaa8d48a9170570d1",
+         "_replication_state":  "triggered",
+         "_replication_state_time":  1297974122
+    }
+
+Now you would like to have the same pull replications going on in server
+D, that is, you would like to have server D pull replicating from
+servers A and B. You have two options:
+
+-  Explicitly add two documents to server's D replicator database
+
+-  Replicate server's C replicator database into server's D replicator
+   database
+
+Both alternatives accomplish exactly the same goal.
+
+Delegations
+~~~~~~~~~~~
+
+Replication documents can have a custom ``user_ctx`` property. This
+property defines the user context under which a replication runs. For
+the old way of triggering replications (POSTing to ``/_replicate/``),
+this property was not needed (it didn't exist in fact) - this is because
+at the moment of triggering the replication it has information about the
+authenticated user. With the replicator database, since it's a regular
+database, the information about the authenticated user is only present
+at the moment the replication document is written to the database - the
+replicator database implementation is like a \_changes feed consumer
+(with ``?include_docs=true``) that reacts to what was written to the
+replicator database - in fact this feature could be implemented with an
+external script/program. This implementation detail implies that for non
+admin users, a ``user_ctx`` property, containing the user's name and a
+subset of his/her roles, must be defined in the replication document.
+This is ensured by the document update validation function present in
+the default design document of the replicator database. This validation
+function also ensure that a non admin user can set a user name property
+in the ``user_ctx`` property that doesn't match his/her own name (same
+principle applies for the roles).
+
+For admins, the ``user_ctx`` property is optional, and if it's missing
+it defaults to a user context with name null and an empty list of roles
+- this mean design documents will not be written to local targets. If
+writing design documents to local targets is desired, the a user context
+with the roles ``_admin`` must be set explicitly.
+
+Also, for admins the ``user_ctx`` property can be used to trigger a
+replication on behalf of another user. This is the user context that
+will be passed to local target database document validation functions.
+
+    **Note**
+
+    The ``user_ctx`` property only has effect for local endpoints.
+
+Example delegated replication document:
+
+::
+
+    {
+         "_id": "my_rep",
+         "source":  "http://bserver.com:5984/foo",
+         "target":  "bar",
+         "continuous":  true,
+         "user_ctx": {
+              "name": "joe",
+              "roles": ["erlanger", "researcher"]
+         }
+    }
+
+As stated before, for admins the user\_ctx property is optional, while
+for regular (non admin) users it's mandatory. When the roles property of
+``user_ctx`` is missing, it defaults to the empty list ``[ ]``.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/3968d980/share/docs/sphinx-docs/views.rst
----------------------------------------------------------------------
diff --git a/share/docs/sphinx-docs/views.rst b/share/docs/sphinx-docs/views.rst
new file mode 100644
index 0000000..48c5a53
--- /dev/null
+++ b/share/docs/sphinx-docs/views.rst
@@ -0,0 +1,2 @@
+Views
+=====


Mime
View raw message