(part of) documentation in sphinx format

docs/sphinx/source/authors.rst

+Authors
+=======
+
+* Francois Billioud
+* Tristan Cavelier
+* Sven Franck
+

docs/sphinx/source/available_storages.rst

+
+
+.. role:: js(code)
+   :language: javascript
+
+
+.. _list-of-available-storages:
+List of Available Storages
+==========================
+
+JIO save his job queue in a workspace which is localStorage by default.
+Provided storage descirption are also stored, and it can be dangerous if we
+store passwords.
+
+The best way to create a storage description is to use the (often) provided
+tool given by the storage library. The returned description is secured to avoid
+clear readable password. (enciphered password for instance)
+
+When building storage trees, there is no limit on the number of storages you
+can use. The only thing you have to be aware of is compatability of simple and
+revision based storages.
+
+
+Connectors
+----------
+
+LocalStorage
+^^^^^^^^^^^^
+
+
+Three methods are provided:
+
+ * :js:`createDescription(username, [application_name], [mode="localStorage"])`
+ * :js:`createLocalDescription(username, [application_name])`
+ * :js:`createMemoryDescription(username, [application_name])`
+
+All parameters are strings.
+
+Examples:
+
+.. code-block:: javascript
+
+    // to work on browser localStorage
+    var jio = jIO.createJIO(local_storage.createDescription("me"));
+
+    // to work on browser memory
+    var jio = jIO.createJIO(local_storage.createMemoryDescription("me"));
+
+
+DavStorage
+^^^^^^^^^^
+
+The tool dav_storage.createDescription generates a dav storage description for
+*no*, *basic* or *digest* authentication (*digest* is not implemented yet).
+
+.. code-block:: javascript
+
+   dav_storage.createDescription(url, auth_type, [realm], [username], [password]);
+
+All parameters are strings.
+
+Only ``url`` and ``auth_type`` are required. If ``auth_type`` is equal to "none",
+then ``realm``, ``username`` and ``password`` are useless. ``username`` and ``password`` become
+required if ``auth_type`` is equal to "basic". And ``realm`` also becomes required if
+``auth_type`` is equal to "digest".
+
+digest **is not implemented yet**
+
+**Be careful**: The generated description never contains readable password, but
+for basic authentication, the password will just be base64 encoded.
+
+S3Storage
+^^^^^^^^^
+
+Updating to v2.0
+
+XWikiStorage
+^^^^^^^^^^^^
+
+Updating to v2.0
+
+Handlers
+--------
+
+IndexStorage
+^^^^^^^^^^^^
+
+This handler indexes documents metadata into a database (which is a simple
+document) to increase the speed of allDocs requests. However, it is not able to
+manage the ``include_docs`` option.
+
+The sub storages have to manage ``query`` and ``include_docs`` options.
+
+Here is the description:
+
+.. code-block:: javascript
+
+   {
+     "type": "index",
+     "indices": [{
+       "id": "index_title_subject.json", // doc id where to store indices
+       "index": ["title", "subject"], // metadata to index
+       "attachment": "db.json", // default "body"
+       "metadata": { // additional metadata to add to database, default undefined
+         "type": "Dataset",
+         "format": "application/json",
+         "title": "My index database",
+         "creator": "Me"
+       },
+       "sub_storage": <sub storage where to store index>
+                      // default equal to parent sub_storage field
+     }, {
+       "id": "index_year.json",
+       "index": "year"
+       ...
+     }],
+     "sub_storage": <sub storage description>
+   }
+
+
+GIDStorage
+^^^^^^^^^^
+
+`Full description here <http://www.j-io.org/P-JIO-GIDStorage>`_.
+
+Updating to v2.0
+
+SplitStorage
+^^^^^^^^^^^^
+
+Updating to v2.0
+
+Replicate Storage
+^^^^^^^^^^^^^^^^^
+
+Comming soon
+
+Revision Based Handlers
+-----------------------
+
+A revision based handler is a storage which is able to do some document
+versionning using simple storages listed above.
+
+On JIO command parameter, ``_id`` is still used to identify a document, but
+another id ``_rev`` must be defined to use a specific revision of this document.
+
+On command responses, you will find another field ``rev`` which will represent the
+new revision produced by your action. All the document history is kept unless
+you decide to delete older revisions.
+
+Another fields ``conflicts``, ``revisions`` and ``revs_info`` can be returned if the
+options **conflicts: true**, **revs: true** and **revs_info: true** are set.
+
+Revision Storage
+^^^^^^^^^^^^^^^^
+
+Updating to v2.0
+
+Replicate Revision Storage
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Updating to v2.0
+
+
+

docs/sphinx/source/complex_queries.rst

+JIO Complex Queries
+===================
+
+What are Complex Queries?
+-------------------------
+
+In jIO, a complex query can tell a storage server to select, filter, sort, or
+limit a document list before sending it back. If the server is not able to do
+so, the complex query tool can act on the retreived list by itself. Only the
+allDocs method can use complex queries.
+
+A query can either be a string (using a specific language useful for writing
+queries), or it can be a tree of objects (useful to browse queries). To handle
+complex queries, jIO uses a parsed grammar file which is complied using `JSCC <http://jscc.phorward-software.com/>`_.
+
+Why use Complex Queries?
+------------------------
+
+Complex queries can be used similar to database queries. So they are useful to:
+
+* search a specific document
+* sort a list of documents in a certain order
+* avoid retreiving a list of ten thousand documents
+* limit the list to show only xy documents by page
+
+For some storages (like localStorage), complex queries can be a powerful tool
+to query accessible documents. When querying documents on a distant storage,
+some server-side logic should be run to avoid having to request large amount of
+documents to run a query on the client. If distant storages are static, an
+alternative would be to use an indexStorage with appropriate indices as complex
+queries will always try to run the query on the index before querying documents
+itself.
+
+How to use Complex Queries with jIO?
+------------------------------------
+
+Complex queries can be triggered by including the option named query in the allDocs method call. An example would be:
+
+.. code-block:: javascript
+
+    var options = {};
+
+    // search text query
+    options['query'] = '(creator:"John Doe") AND (format:"pdf")';
+
+    // OR query tree
+    options['query'] = {
+      type:'complex',
+      operator:'AND',
+      query_list: [{
+        "type": "simple",
+        "key": "creator",
+        "value": "John Doe"
+      }, {
+        "type": "simple",
+        "key": "format",
+        "value": "pdf"
+      }]
+    };
+
+    // FULL example using filtering criteria
+    options = {
+      query: '(creator:"% Doe") AND (format:"pdf")',
+      limit: [0, 100],
+      sort_on: [['last_modified', 'descending'], ['creation_date', 'descending']],
+      select_list: ['title'],
+      wildcard_character: '%'
+    };
+
+    // execution
+    jio_instance.allDocs(options, callback);
+
+
+How to use Complex Queries outside jIO?
+---------------------------------------
+
+Complex Queries provides an API - which namespace is complex_queries. Please
+also refer to the `Complex Queries sample page <http://git.erp5.org/gitweb/jio.git/blob/HEAD:/examples/complex_example.html?js=1>`_
+on how to use these methods in- and outside jIO. The module provides:
+
+.. code-block:: javascript
+
+    {
+      parseStringToObject: [Function: parseStringToObject],
+      stringEscapeRegexpCharacters: [Function: stringEscapeRegexpCharacters],
+      select: [Function: select],
+      sortOn: [Function: sortOn],
+      limit: [Function: limit],
+      convertStringToRegExp: [Function: convertStringToRegExp],
+      QueryFactory: { [Function: QueryFactory] create: [Function] },
+      Query: [Function: Query],
+      SimpleQuery: { [Function: SimpleQuery] super_: [Function: Query] },
+      ComplexQuery: { [Function: ComplexQuery] super_: [Function: Query] }
+    }
+
+(Reference API coming soon.)
+
+Basic example:
+
+.. code-block:: javascript
+
+    // object list (generated from documents in storage or index)
+    var object_list = [
+      {"title": "Document number 1", "creator": "John Doe"},
+      {"title": "Document number 2", "creator": "James Bond"}
+    ];
+
+    // the query to run
+    var query = 'title: "Document number 1"';
+
+    // running the query
+    var result = complex_queries.QueryFactory.create(query).exec(object_list);
+    // console.log(result);
+    // [ { "title": "Document number 1", "creator": "John Doe"} ]
+
+
+Other example:
+
+.. code-block:: javascript
+
+    var result = complex_queries.QueryFactory.create(query).exec(
+      object_list,
+      {
+        "select": ['title', 'year'],
+        "limit": [20, 20], // from 20th to 40th document
+        "sort_on": [['title', 'ascending'], ['year', 'descending']],
+        "other_keys_and_values": "are_ignored"
+      }
+    );
+    // this case is equal to:
+    var result = complex_queries.QueryFactory.create(query).exec(object_list);
+    complex_queries.sortOn([['title', 'ascending'], ['year', 'descending']], result);
+    complex_queries.limit([20, 20], result);
+    complex_queries.select(['title', 'year'], result);
+
+
+Complex Queries in storage connectors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The query exec method must only be used if the server is not able to pre-select
+documents. As mentioned before, you could use an indexStorage to maintain
+indices with key information on all documents in a storage. This index file
+will then be used to run queries on if all fields, required in the query answer
+are available in the index.
+
+Matching properties
+^^^^^^^^^^^^^^^^^^^
+
+Complex Queries select items which exactly match with the value given in the
+query. You can use wildcards ('%' is the default wildcard character), and you
+can change the wildcard character in the query options object. If you don't
+want to use a wildcard, just set the wildcard character to an empty string.
+
+.. code-block:: javascript
+
+    var query = {
+      "query": 'creator:"* Doe"',
+      "wildcard_character": "*"
+    };
+
+
+Should default search types be defined in jIO or in user interface components?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Default search types should be defined in the application's user interface
+components because criteria like filters will be changed frequently by the
+component (change ``limit: [0, 10]`` to ``limit: [10, 10]`` or ``sort_on: [['title',
+'ascending']]`` to ``sort_on: [['creator', 'ascending']]``) and each component must
+have their own default properties to keep their own behavior.
+
+Convert Complex Queries into another type
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example, convert Query object into human readable string:
+
+.. code-block:: javascript
+
+    var query = complex_queries.QueryFactory.create('year: < 2000 OR title: "*a"'),
+      option = {
+        "wildcard_character": "*",
+        "limit": [0, 10]
+      },
+      human_read = {
+        "<": "is lower than ",
+        "<=": "is lower or equal than ",
+        ">": "is greater than ",
+        ">=": "is greater or equal than ",
+        "=": "matches ",
+        "!=": "doesn't match "
+      };
+
+    query.onParseStart = function (object, option) {
+      object.start = "The wildcard character is '" +
+        (option.wildcard_character || "%") +
+        "' and we need only the " + option.limit[1] + " elements from the numero " +
+        option.limit[0] + ". ";
+    };
+
+    query.onParseSimpleQuery = function (object, option) {
+      object.parsed = object.parsed.key + " " + human_read[object.parsed.operator] +
+        object.parsed.value;
+    };
+
+    query.onParseComplexQuery = function (object, option) {
+      object.parsed = "I want all document where " +
+        object.parsed.query_list.join(" " + object.parsed.operator.toLowerCase() +
+        " ") + ". ";
+    };
+
+    query.onParseEnd = function (object, option) {
+      object.parsed = object.start + object.parsed + "Thank you!";
+    };
+
+    console.log(query.parse(option));
+    // logged: "The wildcard character is '*' and we need only the 10 elements
+    // from the numero 0. I want all document where year is lower than 2000 or title
+    // matches *a. Thank you!"
+
+
+JSON Schemas and Grammar
+------------------------
+
+Below you can find schemas for constructing complex queries
+
+* `Complex Queries JSON Schema <http://www.j-io.org/jio-Complex.Queries.JSON.Schema>`_
+* `Simple Queries JSON Schema <http://www.j-io.org/jio-Simple.Queries.JSON.Schema>`_
+* `Complex Queries Grammar <http://www.j-io.org/jio-Complex.Queries.Grammar>`_
+
+

docs/sphinx/source/conf.py

+# -*- coding: utf-8 -*-
+#
+# JIO documentation build configuration file, created by
+# sphinx-quickstart on Fri Nov 15 11:55:08 2013.
+#
+# 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
+
+#highlight_language = 'javascript'
+
+# 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 = ['sphinx.ext.todo', 'sphinx.ext.ifconfig']
+
+# 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'JIO'
+copyright = u'2013, Nexedi'
+
+# 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 = '2.0.0'
+# The full version, including alpha/beta/rc tags.
+release = '2.0.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'
+pygments_style = 'manni'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = 'jio.png'
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'JIOdoc'
+
+
+# -- 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', 'JIO.tex', u'JIO Documentation',
+   u'Nexedi', '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', 'jio', u'JIO Documentation',
+     [u'Nexedi'], 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', 'JIO', u'JIO Documentation',
+   u'Nexedi', 'JIO', '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'

docs/sphinx/source/developers.rst

+For developers
+==============
+
+Quick start
+-----------
+
+To get started with jIO, clone one of the repositories link in `Download & Fork <https://www.j-io.org/download-and-fork>`_ tab.
+
+To build your library you have to:
+
+* Install `NodeJS <http://nodejs.org/>`_ (including NPM)
+* Install Grunt command line with npm. ``# npm -g install grunt-cli``
+* Install dev dependencies. ``$ npm install``
+* Compile JS/CC parser. ``$ make`` (until we found how to compile it with grunt)
+* And run build. ``$ grunt``
+
+The repository also includes the built ready-to-use files, so in case you do
+not want to build jIO yourself, just use *jio.js* as well as *complex_queries.js*
+plus the storages and dependencies you need and you will be good to go.
+
+Naming Conventions
+------------------
+
+All the code follows this `Javascript Naming Conventions <http://www.j-io.org/Javascript-Naming_Conventions>`_.
+
+How to design your own jIO Storage Library
+------------------------------------------
+
+Create a constructor:
+
+.. code-block:: javascript
+
+    function MyStorage(storage_description) {
+      this._value = storage_description.value;
+      if (typeof this._value !== 'string') {
+        throw new TypeError("'value' description property is not a string");
+      }
+    }
+
+Create 10 methods: ``post``, ``put``, ``putAttachment``, ``get``, ``getAttachment``,
+``remove``, ``removeAttachment``, ``allDocs``, ``check`` and ``repair``.
+
+.. code-block:: javascript
+
+    MyStorage.prototype.post = function (command, metadata, option) {
+      var document_id = metadata._id;
+      // [...]
+    };
+
+    MyStorage.prototype.get = function (command, param, option) {
+      var document_id = param._id;
+      // [...]
+    };
+
+    MyStorage.prototype.putAttachment = function (command, param, option) {
+      var document_id = param._id;
+      var attachment_id = param._attachment;
+      var attachment_data = param._blob;
+      // [...]
+    };
+
+    // [...]
+
+
+
+(To help you to design your methods, some tools are provided by jIO.util.)
+
+The first parameter command provides some methods to act on the JIO job:
+
+* ``success``, to tell JIO that the job is successfully terminated
+
+  ``command.success(status[Text], [{custom key to add to the response}]);``
+
+* ``resolve``, is equal to success
+
+* ``error``, to tell JIO that the job cannot be done
+
+  ``command.error(status[Text], [reason], [message], [{custom key to add to the response}])``
+
+* ``retry``, to tell JIO that the job cannot be done now, but can be retried later. (same API than error)
+
+* ``reject``, to tell JIO that the job cannot be done, let JIO to decide to retry or not. (same API than error)
+
+
+The second parameter ``metadata`` or ``param`` is the first parameter given by the JIO user.
+
+The third parameter ``option`` is the option parameter given by the JIO user.
+
+Detail of what should return a method:
+
+* post --> success("created", {"id": new_generated_id})
+
+* put, remove, putAttachment or removeAttachment --> success(204)
+
+* get --> success("ok", {"data": document_metadata})
+
+* getAttachment -->
+
+  success("ok", {"data": binary_string, "content_type": content_type})
+  // or
+  success("ok", {"data": new Blob([data], {"type": content_type})})
+
+* allDocs --> success("ok", {"data": row_object})
+
+* check -->
+
+  .. code-block:: javascript
+
+    // if metadata provides "_id" -> check document state
+    // if metadata doesn't promides "_id" -> check storage state
+    success("no_content")
+    // or
+    error("conflict", "corrupted", "incoherent document or storage")
+
+  repair -->
+
+  .. code-block:: javascript
+
+    // if metadata provides "_id" -> repair document state
+    // if metadata doesn't promides "_id" -> repair storage state
+    success("no_content")
+    // or
+    error("conflict", "corrupted", "impossible to repair document or storage")
+    // DON'T DESIGN STORAGES IF THEIR IS NO WAY TO REPAIR INCOHERENT STATES
+
+After setting up all methods, your storage must be added to jIO. This is done
+using the ``jIO.addStorage()`` method, which requires two parameters: the storage
+type (string) add a constructor (function). It is called like this:
+
+.. code-block:: javascript
+
+    // add custom storage to jIO
+    jIO.addStorage('mystoragetype', MyStorage);
+
+
+Please refer to *localstorage.js* implementation for a good example on how to
+setup a storage and what methods are required. Also keep in mind, that jIO is a
+job-based library, so whenever you trigger a method, a job is created, which
+after being processed returns a response.
+
+Job rules
+---------
+
+jIO job manager will follow several rules set at the creation of a new jIO
+instance. When you try to call a method, jIO will create a job and will make
+sure the job is really necessary and will be executed. Thanks to these job
+rules, jIO knows what to do with the new job before adding it to the queue. You
+can add your own rules like this:
+
+These are the jIO **default rules**:
+
+.. code-block:: javascript
+
+    var jio_instance = jIO.createJIO(storage_description, {
+      "job_rules": [{
+        "code_name": "readers update",
+        "conditions": [
+          "sameStorageDescription",
+          "areReaders",
+          "sameMethod",
+          "sameParameters",
+          "sameOptions"
+        ],
+        "action": "update"
+      }, {
+        "code_name": "metadata writers update",
+        "conditions": [
+          "sameStorageDescription",
+          "areWriters",
+          "useMetadataOnly",
+          "sameMethod",
+          "haveDocumentIds",
+          "sameParameters"
+        ],
+        "action": "update"
+      }, {
+        "code_name": "writers wait",
+        "conditions": [
+          "sameStorageDescription",
+          "areWriters",
+          "haveDocumentIds",
+          "sameDocumentId"
+        ],
+        "action": "wait"
+      }]
+    });
+
+
+The following actions can be used:
+
+* ``ok`` - accept the job
+* ``wait`` - wait until the end of the selected job
+* ``update`` - bind the selected job to this one
+* ``deny`` - reject the job
+
+The following condition function can be used:
+
+* ``sameStorageDescription`` - check if the storage descriptions are different.
+* ``areWriters`` - check if the commands are ``post``, ``put``, ``putAttachment``, ``remove``, ``removeAttachment``, or ``repair``.
+* ``areReaders`` - check if the commands are ``get``, ``getAttachment``, ``allDocs`` or ``check``.
+* ``useMetadataOnly`` - check if the commands are ``post``, ``put``, ``get``, ``remove`` or ``allDocs``.
+* ``sameMethod`` - check if the commands are equal.
+* ``sameDocumentId`` - check if the document ids are equal.
+* ``sameParameters`` - check if the metadata or param are equal in deep.
+* ``sameOptions`` - check if the command options are equal.
+* ``haveDocumentIds`` - test if the two commands contain document ids
+
+Create Job Condition
+--------------------
+
+You can create 2 types of function: job condition, and job comparison.
+
+.. code-block:: javascript
+
+    // Job Condition
+    // Check if the job is a get command
+    jIO.addJobRuleCondition("isGetMethod", function (job) {
+      return job.method === 'get';
+    });
+
+    // Job Comparison
+    // Check if the jobs have the same 'title' property only if they are strings
+    jIO.addJobRuleCondition("sameTitleIfString", function (job, selected_job) {
+      if (typeof job.kwargs.title === 'string' &&
+          typeof selected_job.kwargs.title === 'string') {
+        return job.kwargs.title === selected_job.kwargs.title;
+      }
+      return false;
+    });
+
+
+Add job rules
+-------------
+
+You just have to define job rules in the jIO options:
+
+.. code-block:: javascript
+
+    // Do not accept to post or put a document which title is equal to another
+    // already running post or put document title
+    var jio_instance = jIO.createJIO(storage_description, {
+      "job_rules": [{
+        "code_name": "avoid similar title",
+        "conditions": [
+          "sameStorageDescription",
+          "areWriters",
+          "sameTitleIfString"
+        ],
+        "action": "deny",
+        "before": "writers update" // optional
+        // "after": also exists
+      }]
+    });
+
+
+Clear/Replace default job rules
+-------------------------------
+
+If a job which code_name is equal to readers update, then add this rule will replace it:
+
+.. code-block:: javascript
+
+    var jio_instance = jIO.createJIO(storage_description, {
+      "job_rules": [{
+        "code_name": "readers update",
+        "conditions": [
+          "sameStorageDescription",
+          "areReaders",
+          "sameMethod",
+          "haveDocumentIds"
+          "sameParameters"
+          // sameOptions is removed
+        ],
+        "action": "update"
+      }]
+    });
+
+Or you can just clear all rules before adding other ones:
+
+.. code-block:: javascript
+
+    var jio_instance = jIO.createJIO(storage_description, {
+      "clear_job_rules": true,
+      "job_rules": [{
+        // ...
+      }]
+    });
+

docs/sphinx/source/index.rst

+.. JIO documentation master file, created by
+   sphinx-quickstart on Fri Nov 15 11:55:08 2013.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to JIO's documentation!
+===============================
+
+Contents:
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    manage_documents
+    revision_storages
+    available_storages
+    complex_queries
+    metadata
+    developers
+    authors
+    license
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

docs/sphinx/source/introduction.rst

+
+.. role:: js(code)
+   :language: javascript
+
+Introduction
+============
+
+What is jIO?
+------------
+
+JIO is a JavaScript library that allows to manage JSON documents on local or
+remote storages in asynchronous fashion. jIO is an abstracted API mapped after
+CouchDB, that offers connectors to multiple storages, special handlers to
+enhance functionality (replication, revisions, indexing) and a query module to
+retrieve documents and specific information across storage trees.
+
+How does it work?
+-----------------
+
+JIO is separated into three parts - jIO core and storage library(ies). The core
+is using storage libraries (connectors) to interact with the accociated remote
+storage servers. Some queries can be used on top of the jIO allDocs method to
+query documents based on defined criteria.
+
+JIO uses a job management system, so every method called adds a job into a
+queue. The queue is copied in the browsers local storage (by default), so it
+can be restored in case of a browser crash. Jobs are being invoked
+asynchronously with ongoing jobs not being able to re-trigger to prevent
+conflicts.
+
+Getting started
+---------------
+
+This walkthrough is designed to get you started using a basic jIO instance.
+
+#.  Download jIO core, the storages you want to use as well as the
+    complex-queries scripts as well as the dependencies required for the storages
+    you intend to use.  `[Download & Fork] <https://www.j-io.org/download-and-fork>`_
+
+#.  Add the scripts to your HTML page in the following order:
+
+    .. code-block:: html
+
+        <!-- jio core + dependency -->
+        <script src="sha256.amd.js"></script>
+        <script src="rsvp-custom.js"></script>
+        <script src="jio.js"></script>
+
+        <!-- storages + dependencies -->
+        <script src="complex_queries.js"></script>
+        <script src="localstorage.js"></script>
+        <script src="davstorage.js"></script>
+
+        <script ...>
+
+
+    With require js, the main.js will be like this:
+
+    .. code-block:: javascript
+        :linenos:
+
+        require.config({
+            "paths": {
+                // jio core + dependency
+
+                // the AMD compatible version of sha256.js -> see Download and Fork
+                "sha256": "sha256.amd",
+                "rsvp": "rsvp-custom",
+                "jio": "jio",
+                // storages + dependencies
+                "complex_queries": "complex_queries",
+                "localstorage": "localstorage",
+                "davstorage": "davstorage"
+            }
+        });
+
+
+#.  jIO connects to a number of storages and allows to add handlers (or
+    functions) to specifc storages.
+    You can use both handlers and available storages to build a storage
+    tree across which all documents will be maintained and managed by jIO.
+    
+    See :ref:`List of Available Storages <list-of-available-storages>`.
+
+    .. code-block:: javascript
+
+        // create your jio instance
+        var my_jio = jIO.createJIO(storage_description);
+
+#.  The jIO API provides six main methods to manage documents across the storage(s) specified in your jIO storage tree.
+
+    ==================   =====================================================  ========================================
+    Method               Sample Call                                            Description
+    ==================   =====================================================  ========================================
+    `post`               :js:`my_jio.post(document, [options]);`                Creates a new document
+    `put`                :js:`my_jio.put(document, [options]);`                 Creates/Updates a document
+    `putAttachment`      :js:`my_jio.putAttachement(attachment, [options]);`    Updates/Adds an attachment to a document
+    `get`                :js:`my_jio.get(document, [options]);`                 Reads a document
+    `getAttachment`      :js:`my_jio.getAttachment(attachment, [options]);`     Reads a document attachment
+    `remove`             :js:`my_jio.remove(document, [options]);`              Deletes a document and its attachments
+    `removeAttachment`   :js:`my_jio.removeAttachment(attachment, [options]);`  Deletes a document attachment
+    `allDocs`            :js:`my_jio.allDocs([options]);`                       Retrieves a list of existing documents
+    `check`              :js:`my_jio.check(document, [options]);`               Check the document state
+    `repair`             :js:`my_jio.repair(document, [options]);`              Repair the document
+    ==================   =====================================================  ========================================
+
+

docs/sphinx/source/jio-logo.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="250"
+   height="250"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.3.1 r9886"
+   sodipodi:docname="jio-logo.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.017561"
+     inkscape:cx="197.65953"
+     inkscape:cy="220.57125"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer2"
+     showgrid="false"
+     inkscape:window-width="1366"
+     inkscape:window-height="748"
+     inkscape:window-x="-2"
+     inkscape:window-y="17"
+     inkscape:window-maximized="1">
+    <sodipodi:guide
+       position="0,0"
+       orientation="0,744.09448"
+       id="guide2987" />
+    <sodipodi:guide
+       position="744.09448,0"
+       orientation="-1052.3622,0"
+       id="guide2989" />
+    <sodipodi:guide
+       position="744.09448,1052.3622"
+       orientation="0,-744.09448"
+       id="guide2991" />
+    <sodipodi:guide
+       position="0,1052.3622"
+       orientation="1052.3622,0"
+       id="guide2993" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     style="display:inline"
+     transform="translate(0,-802.36218)">
+    <path
+       style="fill:none;stroke:#000000;stroke-width:12.93378448px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 170.9362,864.54712 0,103.8471"
+       id="path3008"
+       inkscape:connector-curvature="0" />
+  </g>
+  <g
+     inkscape:groupmode="layer"
+     id="layer2"
+     inkscape:label="Layer 2"
+     style="display:inline"
+     transform="translate(0,-802.36218)">
+    <path
+       sodipodi:type="arc"
+       style="color:#000000;fill:none;stroke:#000000;stroke-width:13.67287827;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+       id="path2988-2"
+       sodipodi:cx="221.71036"
+       sodipodi:cy="250.89195"
+       sodipodi:rx="79.000244"
+       sodipodi:ry="79.000244"
+       d="m 300.7106,250.89195 a 79.000244,79.000244 0 1 1 -158.00049,0 79.000244,79.000244 0 1 1 158.00049,0 z"
+       transform="matrix(0.85178613,0,0,0.85178613,-17.864163,748.865)" />
+    <g
+       transform="matrix(22.913133,0,0,25.241134,-5160.1455,-16539.144)"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       id="flowRoot3780">
+      <path
+         d="m 225.958,694.704 c 0.168,0 0.3,0.052 0.396,0.156 0.096,0.104 0.16,0.22 0.192,0.348 0.032,0.128 0.076,0.244 0.132,0.348 0.056,0.104 0.132,0.156 0.228,0.156 0.304,0 0.456,-0.264 0.456,-0.792 l 0,-5.556 c 0,-0.43999 -0.064,-0.71999 -0.192,-0.84 -0.128,-0.12799 -0.436,-0.20799 -0.924,-0.24 l 0,-0.228 3.444,0 0,0.228 c -0.488,0.032 -0.796,0.11201 -0.924,0.24 -0.12,0.12001 -0.18,0.40001 -0.18,0.84 l 0,4.44 c 0,0.752 -0.176,1.336 -0.528,1.752 -0.352,0.408 -0.852,0.612 -1.5,0.612 -0.344,0 -0.628,-0.08 -0.852,-0.24 -0.224,-0.16 -0.336,-0.368 -0.336,-0.624 0,-0.16 0.056,-0.3 0.168,-0.42 0.12,-0.12 0.26,-0.18 0.42,-0.18"
+         style="font-variant:normal;font-stretch:normal;font-family:FreeSerif;-inkscape-font-specification:FreeSerif"
+         id="path3832"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>

docs/sphinx/source/license.rst

+Copyright and license
+=====================
+
+jIO is an open-source library and is licensed under the LGPL license. More
+information on LGPL can be found `here <http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License>`_
+
+

docs/sphinx/source/revision_storages.rst

+Revision Storages: Conflicts and Resolution
+===========================================
+
+
+Why Conflicts can Occur
+-----------------------
+
+Using jIO you can store documents in multiple storage locations. With
+increasing number of users working on a document and some storages not being
+available or responding too slow, conflicts are more likely to occur. JIO
+defines a conflict as multiple versions of a document existing in a storage
+tree and a user trying to save on a version that does not match the latest
+version of the document.
+
+To keep track of document versions a revision storage must be used. When doing
+so, jIO creates a document tree file for every document. This file contains all
+existing versions and their status and is modified whenever a version is
+added/updated/removed or when storages are being synchronized.
+
+How to solve conflicts
+----------------------
+
+Using the document tree, jIO tries to make every version of a document
+available on every storage. When multiple versions of a document exist, jIO
+will select the **latest**, **left-most** version on the document tree, along with the
+conflicting versions (when option **conflicts: true** is set in order for
+developers to setup a routine to solve conflicts.
+
+Technically a conflict is solved by deleting alternative versions of a document
+("cutting leaves off from the document tree"). When a user decides to keep a
+version of a document and manually deletes all conflicting versions, the
+storage tree is updated accordingly and the document is available in a single
+version on all storages.
+
+Simple Conflict Example
+-----------------------
+
+You are keeping a namecard file on your PC updating from your smartphone. Your
+smartphone ran out of battery and is offline when you update your namecard on
+your PC with your new email adress. Someone else change this email from your PC
+and once your smartphone is recharged, you go back online and the previous
+update is executed.
+
+#. Setting up the storage tree
+
+  .. code-block:: javascript
+
+    var jio_instance = jIO.newJio({
+      // replicate revision storage
+      "type":"replicaterevision",
+      "storagelist":[{
+        "type": "revision",
+        "sub_storage": {
+          "type": "dav",
+          ...
+        }
+      }, {
+        "type": "revision",
+        "sub_storage": {
+          "type": "local",
+          ...
+        }
+      }]
+    });
+
+
+#. Create your namecard on your smartphone
+
+   .. code-block:: javascript
+
+     jio_instance.post({
+       "_id": "myNameCard",
+       "email": "me@web.com"
+      }).then(function (response) {
+       // response.id -> "myNameCard"
+       // response.rev -> "1-5782E71F1E4BF698FA3793D9D5A96393"
+     });
+
+   This will create the document on your webDav and local storage
+
+#. Someone else updates your shared namecard on Webdav
+
+   .. code-block:: javascript
+
+     jio_instance.put({
+       "email": "my_new_me@web.com",
+       "_id": "myNameCard"
+       "_rev": "1-5782E71F1E4BF698FA3793D9D5A96393"
+     }).then(function (response) {
+       // response.id -> "myNameCard"
+       // response.rev -> "2-068E73F5B44FEC987B51354DFC772891"
+     });
+
+   Your smartphone is offline, so you will now have one version (1-578...) on
+   your smartphone and another version on webDav (2-068...) on your PC.
+
+#. You modify your namecard while being offline
+
+   .. code-block:: javascript
+
+     jio_instance.get({"_id": "myNameCard"}).then(function (response) {
+       // response.id -> "myNameCard"
+       // response.rev -> "1-5782E71F1E4BF698FA3793D9D5A96393"
+       // response.data.email -> "me@web.com"
+
+       return jio_instance.put({
+         "_id": "myNameCard",
+         "email": "me_again@web.com"
+       });
+
+     }).then(function (response) {
+       // response.id -> "myNameCard"
+       // response.rev -> "2-3753476B70A49EA4D8C9039E7B04254C"
+     });
+
+
+#. Later, your smartphone is online and you retrieve your namecard.
+
+   .. code-block:: javascript
+
+     jio_instance.get({"_id": "myNameCard"}).then(function (response) {
+       // response.id -> "myNameCard"
+       // response.rev -> "2-3753476B70A49EA4D8C9039E7B04254C"
+       // response.data.email -> "me_again@web.com"
+     });
+
+   When multiple versions of a document are available, jIO returns the lastest, left-most version on the document tree (2-375... and labels all other versions as conflicting 2-068...).
+
+#. Retrieve conflicts by setting option
+
+   .. code-block:: javascript
+
+     jio_instance.get({"_id": "myNameCard"}, {
+       "conflicts": true
+     }).then(function (response) {
+       // response.id -> "myNameCard"
+       // response.rev -> "2-3753476B70A49EA4D8C9039E7B04254C",
+       // response.conflicts -> ["2-068E73F5B44FEC987B51354DFC772891"]
+     });
+
+   The conflicting version (*2-068E...*) is displayed, because **{conflicts: true}** was
+   specified in the GET call. Deleting either version will solve the conflict.
+
+#. Delete conflicting version
+
+   .. code-block:: javascript
+
+     jio_instance.remove({
+       "_id": "myNameCard",
+       "_rev": "2-068E73F5B44FEC987B51354DFC772891"
+     }).then(function (response) {
+       // response.id -> "myNameCard"
+       // response.rev -> "3-28910A4937537B5168E772896B70EC98"
+     });
+
+   When deleting the conflicting version of your namecard, jIO removes this
+   version from all storages and sets the document tree leaf of this version to
+   deleted. All storages now contain just a single version of your namecard
+   (2-3753...). Note, that the on the document tree, removing a revison will
+   create a new revision with status set to *deleted*.
+