Commits

Anonymous committed 5225f08 Draft

reorganized documentation

Comments (0)

Files changed (4)

-.. warning:: This is alpha-stage software. Use with caution.
+araldo
 
-araldo
-######
+**This is alpha software. Use with caution**
 
 *araldo* provides a simple, extensible communication relay (based on `gevent <http://www.gevent.org/>`_ and `WebSockets <http://en.wikipedia.org/wiki/WebSocket>`_) between multiple endpoints
 
 
 - `Repository and issue tracker: <http://bitbucket.org/ganymed/araldo>`_
 - `Documentation of in-development version <https://araldo.readthedocs.org/en/latest/>`_
-
-Use cases
-*********
-
-- Push notification from server to Browser
-- Bidirectional communication between browsers
-- Bidirectional communication between browsers and a backend
-- Interoperability between different message-oriented middleware products
-
-Architecture
-************
-
-*araldo* is a central server component that provides an arbitrary amount of 
-endpoints to which clients may connect, or which connect to other servers.
-
-Routes
-======
-*araldo* uses the concept of *routes* for setting up communication. Rather than
-relying on clients subscribing/publishing to/from particular channels, the channel
-setup and routing between endpoints is done inside *araldo*.
-
-Implementation
-==============
-
-*araldo* uses `gevent <http://www.gevent.org/>`_, a corouting-based networking
-library. *gevent* uses `green threads <http://en.wikipedia.org/wiki/Green_threads>`_ (greenlets) and asynchronous IO. Therefore, 
-the *araldo* server is single-threaded with respect to native threads, but highly
-concurrent with respect to green threads.
-
-Plugins
-=======
-
-Available Plugins
------------------
-
-*araldo* consists of a core that is run as a server process, and several plugins.
-Available plugins are loaded automatically. Out of the box, *araldo* provides a 
-`WebSocket <http://en.wikipedia.org/wiki/WebSocket>`_ server that allows multiple clients
-to communicate with each other via routes.
- 
-
-Currently the following plugins are available:
-
-===================  ========================== ==============================================
-Name                 Description                Link
-===================  ========================== ==============================================
-araldo-redis         Communication via Redis    http://bitbucket.org/ganymed/araldo-redis
-                     PubSub
-araldo-websocket     Communication with an      http://bitbucket.org/ganymed/araldo-websocket
-                     HTML5 WebSocket server
-===================  ========================== ==============================================
-
-Extensibility
--------------
-
-*araldo* uses the Python entry-point mechanism for plugin discovery.
-
-Installation
-************
-
-To install *araldo* along with some plugins, type::
-
- pip install araldo
-
-Configuration
-*************
-
-Command line parameters::
-
-  Usage: server.py [options]
-
-  Options:
-    -h, --help                  show this help message and exit
-    -c CONFIG, --config=CONFIG
-                                Configuration path
-
-
-Configuration File
-==================
-
-The configuration file in *YAML* format mainly contains 
- 
-- global settings
-- plugin instances, with plugin-specific settings
-- routes (connections between endpoints)
-
-The standard configuration file is ``araldo.yaml`` in the current directory.
-
-Global parameters
-=================
-
-============== ========= ============================================
-Parameter      Type      Description
-============== ========= ============================================
-server-port    int       TCP port of web (WebSocket) server
-log-level      str       One of ``debug``, ``info``, ``warning``, 
-                         ``error``, ``fatal``.
-                         Verbosity of logging
-============== ========= ============================================
-
-Plugin-Specific parameters
-==========================
-
-Plugins are configured under the toplevel configuration key ``plugins``.
-
-All plugins
-----------------------
-
-============== ========= ============================================
-Parameter      Type      Description
-============== ========= ============================================
-name           str       Unique name for the plugin instance
-id             str       Identifier for the plugin type
-============== ========= ============================================
-
-
-Routing
-=======
-Routes map messages from an inbound source to multiple outbound endpoints.
-Routing is configured under the toplevel configuration key ``routes``. Each 
-route consists of a key that references a name of an endpoint. The value is 
-a list of names referencing other endpoints.
-
-Sample configuration::
-
-  global:
-      server-port: 54321
-      log-level: debug
-  
-  plugins:
-    araldo.marshalling:
-      - name: marshal-json
-        id: marshal-json
-    araldo.endpoints.endpoint:
-      - name: mock_1
-        id: endpoint-mock
-        channel: channel_1
-      - name: redis_2
-        id: endpoint-mock
-        channel: channel_2
-      - name: redis_3
-        id: endpoint-mock
-        channel: channel_3
-  
-  routes:
-    redis_1:
-      - redis_2
-      - redis_3
-
-Platform & System Requirements
-******************************
-
-- *araldo* has been tested under Python 2.6 and 2.7. Python 3.x is not 
-  supported because not all libraries it depends on currently support 3.x.
-- *araldo* was tested exclusively under Linux.

doc/README.rst

-../README.rst
+
+.. warning:: This is alpha-stage software. Use with caution.
+
+araldo
+######
+
+*araldo* provides a simple, extensible communication relay (based on `gevent <http://www.gevent.org/>`_ and `WebSockets <http://en.wikipedia.org/wiki/WebSocket>`_) between multiple endpoints
+
+Resources:
+
+- `Repository and issue tracker: <http://bitbucket.org/ganymed/araldo>`_
+- `Documentation of in-development version <https://araldo.readthedocs.org/en/latest/>`_
+
+Use cases
+*********
+
+- Push notification from server to Browser
+- Bidirectional communication between browsers
+- Bidirectional communication between browsers and a backend
+- Interoperability between different message-oriented middleware products
+
+Architecture
+************
+
+*araldo* is a central server component that provides an arbitrary amount of 
+endpoints to which clients may connect, or which connect to other servers.
+
+Routes
+======
+*araldo* uses the concept of *routes* for setting up communication. Rather than
+relying on clients subscribing/publishing to/from particular channels, the channel
+setup and routing between endpoints is done inside *araldo*.
+
+Implementation
+==============
+
+*araldo* uses `gevent <http://www.gevent.org/>`_, a corouting-based networking
+library. *gevent* uses `green threads <http://en.wikipedia.org/wiki/Green_threads>`_ (greenlets) and asynchronous IO. Therefore, 
+the *araldo* server is single-threaded with respect to native threads, but highly
+concurrent with respect to green threads.
+
+Plugins
+=======
+
+Available Plugins
+-----------------
+
+*araldo* consists of a core that is run as a server process, and several plugins.
+Available plugins are loaded automatically. Out of the box, *araldo* provides a 
+`WebSocket <http://en.wikipedia.org/wiki/WebSocket>`_ server that allows multiple clients
+to communicate with each other via routes.
+ 
+
+Currently the following plugins are available:
+
+===================  ========================== ==============================================
+Name                 Description                Link
+===================  ========================== ==============================================
+araldo-redis         Communication via Redis    http://bitbucket.org/ganymed/araldo-redis
+                     PubSub
+araldo-websocket     Communication with an      http://bitbucket.org/ganymed/araldo-websocket
+                     HTML5 WebSocket server
+===================  ========================== ==============================================
+
+Extensibility
+-------------
+
+*araldo* uses the Python entry-point mechanism for plugin discovery.
+
+Installation
+************
+
+To install *araldo* along with some plugins, type::
+
+ pip install araldo
+
+Configuration
+*************
+
+Command line parameters::
+
+  Usage: server.py [options]
+
+  Options:
+    -h, --help                  show this help message and exit
+    -c CONFIG, --config=CONFIG
+                                Configuration path
+
+
+Configuration File
+==================
+
+The configuration file in *YAML* format mainly contains 
+ 
+- global settings
+- plugin instances, with plugin-specific settings
+- routes (connections between endpoints)
+
+The standard configuration file is ``araldo.yaml`` in the current directory.
+
+Global parameters
+=================
+
+============== ========= ============================================
+Parameter      Type      Description
+============== ========= ============================================
+server-port    int       TCP port of web (WebSocket) server
+log-level      str       One of ``debug``, ``info``, ``warning``, 
+                         ``error``, ``fatal``.
+                         Verbosity of logging
+============== ========= ============================================
+
+Plugin-Specific parameters
+==========================
+
+Plugins are configured under the toplevel configuration key ``plugins``.
+
+All plugins
+----------------------
+
+============== ========= ============================================
+Parameter      Type      Description
+============== ========= ============================================
+name           str       Unique name for the plugin instance
+id             str       Identifier for the plugin type
+============== ========= ============================================
+
+
+Routing
+=======
+Routes map messages from an inbound source to multiple outbound endpoints.
+Routing is configured under the toplevel configuration key ``routes``. Each 
+route consists of a key that references a name of an endpoint. The value is 
+a list of names referencing other endpoints.
+
+Sample configuration::
+
+  global:
+      server-port: 54321
+      log-level: debug
+  
+  plugins:
+    araldo.marshalling:
+      - name: marshal-json
+        id: marshal-json
+    araldo.endpoints.endpoint:
+      - name: mock_1
+        id: endpoint-mock
+        channel: channel_1
+      - name: redis_2
+        id: endpoint-mock
+        channel: channel_2
+      - name: redis_3
+        id: endpoint-mock
+        channel: channel_3
+  
+  routes:
+    redis_1:
+      - redis_2
+      - redis_3
+
+Platform & System Requirements
+******************************
+
+- *araldo* has been tested under Python 2.6 and 2.7. Python 3.x is not 
+  supported because not all libraries it depends on currently support 3.x.
+- *araldo* was tested exclusively under Linux.
 .. toctree::
    :maxdepth: 2
 
-   README.rst
+   araldo.rst
    API.rst