couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From deathb...@apache.org
Subject [02/50] [abbrv] git commit: updated refs/heads/replicator-redesign to 066d69b
Date Tue, 01 Oct 2013 13:46:12 GMT
Externals API article cleanup.


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

Branch: refs/heads/replicator-redesign
Commit: b35bf757e2376dac20b5a295e08bf208e5aa3ba0
Parents: fe79a4d
Author: Alexander Shorin <kxepal@apache.org>
Authored: Sun Aug 25 16:52:13 2013 +0400
Committer: Alexander Shorin <kxepal@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400

----------------------------------------------------------------------
 share/doc/src/externals.rst | 77 ++++++++++++++++++----------------------
 1 file changed, 35 insertions(+), 42 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb/blob/b35bf757/share/doc/src/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/externals.rst b/share/doc/src/externals.rst
index 10ed34a..9b4530f 100644
--- a/share/doc/src/externals.rst
+++ b/share/doc/src/externals.rst
@@ -19,9 +19,10 @@ CouchDB Externals API
 
 :Author: Paul Joseph Davis
 :Date: 2010-09-26
+:Source: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
 
-For a bit of background, CouchDB has had an API for managing external OS
-processes [1] that are capable of handling HTTP requests for a given
+For a bit of background, CouchDB has had an API for managing `external OS
+processes`_ that are capable of handling HTTP requests for a given
 URL prefix. These OS processes communicate with CouchDB using JSON over
 stdio. They're dead simple to write and provide CouchDB users an easy way to
 extend CouchDB functionality.
@@ -50,7 +51,7 @@ fringe benefits as well. I'm always a fan of extra awesomeness.
 
 After hitting on the idea of adding a reverse proxy, people quickly pointed
 out that it would require users to start manually managing their external
-processes using something like Runit [2] or Supervisord [3]. After some
+processes using something like `Runit`_ or `Supervisord`_. After some
 more discussions I ran into people that wanted something like _externals that
 didn't handle HTTP requests. After that it was easy to see that adding a second
 feature that managed OS processes was the way to go.
@@ -60,26 +61,23 @@ of working but requiring more testing. In the case of the HTTP proxy I
have no
 tests because I can't decide how to test the thing. If you have ideas, I'd
 sure like to hear them.
 
-[Update]: I woke up the other morning realizing that I was being an idiot and
-that Erlang is awesome. There's no reason that I can't have an HTTP client,
+**[Update]**: I woke up the other morning realizing that I was being an idiot
+and that Erlang is awesome. There's no reason that I can't have an HTTP client,
 proxy, and server all hosted in the same process. So that's what I did. It
 turns out to be a fairly nice way of configuring matching assertions between
 the client and the server to test the proxy transmissions.
 
-The code for both features is in this branch:
-
-    http://github.com/davisp/couchdb/tree/new_externals
-
 How does it work? - HTTP Proxying
 ---------------------------------
 
-To configure a proxy handler, edit your local.ini and add a section like such:
+To configure a :ref:`proxy handler <config/proxy>`, edit your `local.ini` and
+add a section like such::
 
     [httpd_global_handlers]
     _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}
 
-This would be approximately what you'd need to do to get CouchDB-Lucene handled
-through this interface. The URL you use to access a query would be:
+This would be approximately what you'd need to do to get `CouchDB-Lucene`_
+handled through this interface. The URL you use to access a query would be:
 
     http://127.0.0.1:5984/_fti/db_name/_design/foo/by_content?q=hello
 
@@ -105,7 +103,7 @@ one instance of it is alive. If you have something where you want multiple
 processes, you need to either tell CouchDB about each one, or have a main
 process that forks off the required sub-processes.
 
-To configure an OS daemon, add this to your local.ini::
+To configure an :ref:`OS daemon <config/os_daemons>`, add this to your local.ini::
 
     [os_daemons]
     my_daemon = /path/to/command -with args
@@ -116,8 +114,8 @@ Configuration API
 As an added benefit, because stdio is now free, I implemented a simple API
 that OS daemons can use to read the configuration of their CouchDB host. This
 way you can have them store their configuration inside CouchDB's config system
-if you desire. Or they can peek at things like the bind_address and port that
-CouchDB is using.
+if you desire. Or they can peek at things like the :ref:`bind_address
+<config/httpd/bind_address>` and port that CouchDB is using.
 
 A request for a config section looks like this::
 
@@ -135,7 +133,7 @@ And the response::
 
     "/path/to/command -with args"\n
 
-All requests and responses are terminated with a newline (indicated by \n).
+All requests and responses are terminated with a newline (indicated by ``\n``).
 
 Logging API
 +++++++++++
@@ -144,24 +142,26 @@ There's also an API for adding messages to CouchDB's logs. Its simply::
 
     ["log", $MESG]\n
 
-Where $MESG is any arbitrary JSON. There is no response from this command. As
-with the config API, the trailing "\n" represents a newline byte.
+Where ``$MESG`` is any arbitrary JSON. There is no response from this command. As
+with the config API, the trailing ``\n`` represents a newline byte.
 
 Dynamic Daemons
 +++++++++++++++
 
 The OS daemons react in real time to changes to the configuration system. If
-you set or delete keys in the os_daemons section, the corresponding daemons
-will be started or killed as appropriate.
+you set or delete keys in the :ref:`os_daemons <config/os_daemons>` section,
+the corresponding daemons will be started or killed as appropriate.
 
 Neat. But So What?
 ------------------
 
-It was suggested that a good first demo would be  a Node.js [5] handler. So, I
+It was suggested that a good first demo would be  a `Node.js`_ handler. So, I
 present to you a "Hello, World" Node.js handler. Also, remember that this
-currently relies on code in my fork on GitHub [6].
+currently relies on code in my fork on `GitHub`_.
+
+File `node-hello-world.js`:
 
-File `node-hello-world.js`::
+.. code-block:: javascript
 
     var http = require('http');
     var sys = require('sys');
@@ -202,7 +202,9 @@ File `node-hello-world.js`::
 
     console.log(JSON.stringify(["get", "node_hello", "port"]));
 
-File `local.ini` (Just add these to what you have)::
+File `local.ini` (Just add these to what you have):
+
+.. code-block:: ini
 
     [log]
     level = info
@@ -216,7 +218,9 @@ File `local.ini` (Just add these to what you have)::
     [httpd_global_handlers]
     _hello = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:8000">>}
 
-And then start CouchDB and try::
+And then start CouchDB and try:
+
+.. code-block:: bash
 
     $ curl -v http://127.0.0.1:5984/_hello
     * About to connect() to 127.0.0.1 port 5984 (#0)
@@ -247,20 +251,9 @@ The corresponding CouchDB logs look like::
     [info] [<0.95.0>] Daemon "node-hello" :: GET /
 
 
-[1]:  http://wiki.apache.org/couchdb/ExternalProcesses
-[2]:  http://smarden.org/runit/
-[3]:  http://supervisord.org/
-[4]:  http://www.mikealrogers.com/
-[5]:  http://nodejs.org/
-[6]:  http://github.com/davisp/couchdb/tree/new_externals
-
-
-Copyright Notice
-----------------
-
-Copyright 2008-2010 Paul Joseph Davis
-
-License
--------
-
-http://creativecommons.org/licenses/by/3.0/
+.. _external OS processes: http://wiki.apache.org/couchdb/ExternalProcesses
+.. _Runit: http://smarden.org/runit/
+.. _Supervisord: http://supervisord.org/
+.. _Node.js: http://nodejs.org/
+.. _GitHub: http://github.com/davisp/couchdb/tree/new_externals
+.. _CouchDB-Lucene: https://github.com/rnewson/couchdb-lucene


Mime
View raw message