Restructured documentation.

README.rst

@@ -0,0 +1,17 @@
+JavaScript Object to DOM
+========================
+
+This library makes the creation of (part of) a Document Object Model (DOM)
+easier by providing a function that converts a nested JavaScript Object (JSO)
+to a DOM. This eliminates the need for manual element and text creation,
+hierarchical placement of elements, attribute setting and configuration of
+callback functions, resulting in more readable and compact code.
+
+This library was originally developed for Greasemonkey_ user scripts, but it
+should be usable in any JavaScript program that runs in a browser.
+
+Please see ReadTheDocs_ for the latest documentation.
+
+
+.. _Greasemonkey: https://www.greasespot.net/
+.. _ReadTheDocs: http://jso-dom.readthedocs.io/en/latest/index.html

docs/credits.rst

@@ -0,0 +1,10 @@
+Contributors
+============
+
+- Jeroen F.J. Laros <jlaros@fixedpoint.nl> (Original author, maintainer)
+
+Find out who contributed:
+
+::
+
+    git shortlog -s -e

docs/index.rst

@@ -0,0 +1,12 @@
+.. doc_test documentation.
+
+.. include:: ../README.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   introduction
+   installation
+   usage
+   credits

docs/installation.rst

@@ -0,0 +1,11 @@
+Installation
+============
+
+In a Greasemonkey user script, add the following line to the ``UserScript``
+header:
+
+.. code:: javascript
+
+    // @require     https://github.com/jfjlaros/jso-dom/raw/master/src/jso_dom.js
+
+This makes the function ``JSOToDOM()`` available.

docs/introduction.rst

@@ -0,0 +1,81 @@
+Introduction
+============
+
+Suppose we want to add a section containing a title with an id, some verbatim
+text and a list to a website, the following code would be required:
+
+.. code:: javascript
+
+    var root, temp, parent, child;
+
+    root = document.createElement("div");
+    parent = document.createElement("h3");
+    parent.setAttribute("id", "title_1");
+    child = document.createTextNode("A title");
+    parent.appendChild(child);
+    root.appendChild(parent);
+
+    parent = document.createElement("pre");
+    child = document.createTextNode("Verbatim text.");
+    parent.appendChild(child);
+    root.appendChild(parent);
+
+    temp = document.createElement("ul");
+    parent = document.createElement("li");
+    child = document.createTextNode("one");
+    parent.appendChild(child);
+    temp.appendChild(parent);
+
+    parent = document.createElement("li");
+    child = document.createTextNode("two");
+    parent.appendChild(child);
+    temp.appendChild(parent);
+
+    parent = document.createElement("li");
+    child = document.createTextNode("three");
+    parent.appendChild(child);
+    temp.appendChild(parent);
+    root.appendChild(temp);
+
+Resulting in the following HTML tree:
+
+.. code:: html
+
+    <div>
+      <h3 id="title_1">A title</h3>
+      <pre>Verbatim text.</pre>
+      <ul>
+        <li>one</li>
+        <li>two</li>
+        <li>three</li>
+      </ul>
+    </div>
+
+Some drawbacks of this manual creation are immediately apparent:
+
+-  Quite some code is required to create a modestly sized HTML tree.
+-  We need to keep track of quite a number of variables, this number grows as
+   the depth of the tree increases.
+-  The nested structure of HTML tree is not apparent which makes code
+   maintenance difficult.
+
+To address these problems, this library provides the function ``JSOToDOM()``
+which takes a nested JSO as input and outputs a DOM. The following call to this
+function creates the HTML tree from our example:
+
+.. code:: javascript
+
+    var root = JSOToDOM({
+      "div": {
+        "h3": {
+            "attrs": {"id": "title_1"},
+          "text": "A title"},
+        "pre": {
+          "text": "Verbatim text."},
+        "ul": [
+          {"li": {"text": "one"}},
+          {"li": {"text": "two"}},
+          {"li": {"text": "three"}}]}});
+
+This code is a lot more compact than the original and arguably more readable
+and therefore more maintainable.