Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 251A5DFB4 for ; Fri, 14 Sep 2012 10:17:39 +0000 (UTC) Received: (qmail 94394 invoked by uid 500); 14 Sep 2012 10:17:22 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 93901 invoked by uid 500); 14 Sep 2012 10:17:16 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 91006 invoked by uid 99); 14 Sep 2012 10:16:59 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 14 Sep 2012 10:16:59 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 915943683B; Fri, 14 Sep 2012 10:16:59 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: dch@apache.org To: commits@couchdb.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [15/49] Clean up imported .rst Message-Id: <20120914101659.915943683B@tyr.zones.apache.org> Date: Fri, 14 Sep 2012 10:16:59 +0000 (UTC) http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/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 deleted file mode 100644 index 9a35030..0000000 --- a/share/docs/sphinx-docs/api/misc.rst +++ /dev/null @@ -1,606 +0,0 @@ -===================== -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/010be920/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 deleted file mode 100644 index 0bbe2cb..0000000 --- a/share/docs/sphinx-docs/api/reference.rst +++ /dev/null @@ -1,16 +0,0 @@ -API Reference -============= - -Contents: - -.. toctree:: - :maxdepth: 2 - - configuration - authn - database - documents - design - misc - local - dbmaint http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/docs/sphinx-docs/changes.rst ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/changes.rst b/share/docs/sphinx-docs/changes.rst deleted file mode 100644 index 29d31ec..0000000 --- a/share/docs/sphinx-docs/changes.rst +++ /dev/null @@ -1,26 +0,0 @@ -============ -Changes Feed -============ - -  - -Polling -======= - -  - -Long Polling -============ - -  - -Continuous -========== - -  - -Filters -======= - -  - http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/docs/sphinx-docs/conf.py ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/conf.py b/share/docs/sphinx-docs/conf.py deleted file mode 100644 index 0db0ec7..0000000 --- a/share/docs/sphinx-docs/conf.py +++ /dev/null @@ -1,242 +0,0 @@ -# -*- 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 -# " v 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 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/010be920/share/docs/sphinx-docs/config.rst ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/config.rst b/share/docs/sphinx-docs/config.rst deleted file mode 100644 index c67e608..0000000 --- a/share/docs/sphinx-docs/config.rst +++ /dev/null @@ -1,105 +0,0 @@ -============================= -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/010be920/share/docs/sphinx-docs/configuring.rst ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/configuring.rst b/share/docs/sphinx-docs/configuring.rst deleted file mode 100644 index 1f0059c..0000000 --- a/share/docs/sphinx-docs/configuring.rst +++ /dev/null @@ -1,210 +0,0 @@ -=================== -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/010be920/share/docs/sphinx-docs/errors.rst ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/errors.rst b/share/docs/sphinx-docs/errors.rst deleted file mode 100644 index 13f93a9..0000000 --- a/share/docs/sphinx-docs/errors.rst +++ /dev/null @@ -1,26 +0,0 @@ -============== -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/010be920/share/docs/sphinx-docs/features.rst ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/features.rst b/share/docs/sphinx-docs/features.rst deleted file mode 100644 index 640407b..0000000 --- a/share/docs/sphinx-docs/features.rst +++ /dev/null @@ -1,193 +0,0 @@ -========================== -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/010be920/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 deleted file mode 100644 index c8c1b9d..0000000 Binary files a/share/docs/sphinx-docs/images/futon-createdb.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/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 deleted file mode 100644 index 6802c2c..0000000 Binary files a/share/docs/sphinx-docs/images/futon-editdoc.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/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 deleted file mode 100644 index 5c8b549..0000000 Binary files a/share/docs/sphinx-docs/images/futon-editeddoc.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/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 deleted file mode 100644 index d1eac6e..0000000 Binary files a/share/docs/sphinx-docs/images/futon-overview.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/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 deleted file mode 100644 index d904f0d..0000000 Binary files a/share/docs/sphinx-docs/images/futon-replform.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/docs/sphinx-docs/index.rst ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/index.rst b/share/docs/sphinx-docs/index.rst deleted file mode 100644 index cf6abec..0000000 --- a/share/docs/sphinx-docs/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. 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/010be920/share/docs/sphinx-docs/intro.rst ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/intro.rst b/share/docs/sphinx-docs/intro.rst deleted file mode 100644 index ea59cf1..0000000 --- a/share/docs/sphinx-docs/intro.rst +++ /dev/null @@ -1,285 +0,0 @@ -============ -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/010be920/share/docs/sphinx-docs/make.bat ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/make.bat b/share/docs/sphinx-docs/make.bat deleted file mode 100644 index 4994199..0000000 --- a/share/docs/sphinx-docs/make.bat +++ /dev/null @@ -1,190 +0,0 @@ -@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 ^` where ^ 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/010be920/share/docs/sphinx-docs/replication.rst ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/replication.rst b/share/docs/sphinx-docs/replication.rst deleted file mode 100644 index 9fadc6e..0000000 --- a/share/docs/sphinx-docs/replication.rst +++ /dev/null @@ -1,371 +0,0 @@ -=========== -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/010be920/share/docs/sphinx-docs/views.rst ---------------------------------------------------------------------- diff --git a/share/docs/sphinx-docs/views.rst b/share/docs/sphinx-docs/views.rst deleted file mode 100644 index 48c5a53..0000000 --- a/share/docs/sphinx-docs/views.rst +++ /dev/null @@ -1,2 +0,0 @@ -Views -===== http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/1.1/commonjs.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/1.1/commonjs.rst b/share/sphinx-docs/1.1/commonjs.rst new file mode 100644 index 0000000..113c024 --- /dev/null +++ b/share/sphinx-docs/1.1/commonjs.rst @@ -0,0 +1,52 @@ +Added CommonJS support to map functions +======================================= + +We didn't have `CommonJS`_ require in map functions because the current +CommonJS implementation is scoped to the whole design doc, and giving +views access to load code from anywhere in the design doc would mean +we'd have to blow away your view index any time you changed anything. +Having to rebuild views from scratch just because you changed some CSS +or a show function isn't fun, so we avoided the issue by keeping +CommonJS require out of map and reduce altogether. + +The solution we came up with is to allow CommonJS 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. + +We simplified the implementation 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: + +.. code-block:: javascript + + { + "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. + +.. _CommonJS: http://commonjs.org/specs http://git-wip-us.apache.org/repos/asf/couchdb/blob/010be920/share/sphinx-docs/1.1/index.rst ---------------------------------------------------------------------- diff --git a/share/sphinx-docs/1.1/index.rst b/share/sphinx-docs/1.1/index.rst new file mode 100644 index 0000000..c77845a --- /dev/null +++ b/share/sphinx-docs/1.1/index.rst @@ -0,0 +1,35 @@ +================================= +CouchDB Release 1.1 Feature Guide +================================= + +Upgrading to CouchDB 1.1 +======================== + +You can upgrade your existing CouchDB 1.0.x installation to CouchDB 1.1 +without any specific steps or migration. When you run CouchDB 1.1 the +existing data and index files will be opened and used as normal. + +The first time you run a compaction routine on your database within +CouchDB 1.1, the data structure and indexes will be updated to the new +version of the CouchDB database format that can only be read by CouchDB +1.1 and later. This step is not reversible. Once the data files have +been updated and migrated to the new version the data files will no +longer work with a CouchDB 1.0.x release. + +.. warning:: + If you want to retain support for opening the data files in + CouchDB 1.0.x you must back up your data files before performing the + upgrade and compaction process. + +New features in CouchDB 1.1 +=========================== + +.. toctree:: + :maxdepth: 2 + + replicator + ssl + range + proxy + commonjs + other