Add sphinx documentation for jsinput

doc/public/course_data_formats/jsinput.rst

+##############################################################################
+JS Input
+##############################################################################
+
+    **NOTE** 
+    *Do not use this feature yet! Its attributes and behaviors may change
+    without any concern for backwards compatibility. Moreover, it has only been
+    tested in a very limited context. If you absolutely must, contact Julian
+    (julian@edx.org). When the feature stabilizes, this note will be removed.*
+     
+This document explains how to write a JSInput input type. JSInput is meant to
+allow problem authors to easily turn working standalone HTML files into
+problems that can be integrated into the edX platform. Since it's aim is
+flexibility, it can be seen as the input and client-side equivalent of
+CustomResponse.
+
+A JSInput input creates an iframe into a static HTML page, and passes the
+return value of author-specified functions to the enclosing response type
+(generally CustomResponse). JSInput can also stored and retrieve state.
+
+******************************************************************************
+Format
+******************************************************************************
+
+A jsinput problem looks like this:
+
+.. code-block:: xml
+
+    <problem>
+        <script type="loncapa/python">
+ def all_true(exp, ans): return ans == "hi"
+        </script>
+        <customresponse cfn="all_true">
+            <jsinput gradefn="gradefn" 
+                height="500"
+                get_statefn="getstate"
+                set_statefn="setstate"
+                html_file="/static/jsinput.html"/>
+        </customresponse>
+    </problem>
+
+The accepted attributes are:
+
+==============  ==============  ========= ==========
+Attribute Name   Value Type     Required?  Default
+==============  ==============  ========= ==========
+html_file        Url string     Yes        None
+gradefn          Function name  Yes        `gradefn`
+set_statefn      Function name  No         None
+get_statefn      Function name  No         None
+height           Integer        No         `500`
+width            Integer        No         `400`
+==============  ==============  ========= ==========
+
+******************************************************************************
+Required Attributes
+******************************************************************************
+
+==============================================================================
+html_file
+==============================================================================
+
+The `html_file` attribute specifies what html file the iframe will point to. This
+should be located in the content directory.
+
+The iframe is created using the sandbox attribute; while popups, scripts, and
+pointer locks are allowed, the iframe cannot access its parent's attributes.
+
+The html file should contain a top-level function for the gradefn function. To
+check whether the gradefn will be accessible to JSInput, check that, in the
+console,::
+    window["`gradefn`"]
+Returns the right thing.
+
+Aside from that, more or less anything goes. Note that currently there is no
+support for inheriting css or javascript from the parent (aside from the
+Chrome-only `seamless` attribute, which is set to true by default).
+
+==============================================================================
+gradefn
+==============================================================================
+
+The `gradefn` attribute specifies the name of the function that will be called
+when a user clicks on the "Check" button, and which should return the student's
+answer. This answer will (unless both the get_statefn and set_statefn
+attributes are also used) be passed as a string to the enclosing response type.
+In the customresponse example above, this means cfn will be passed this answer
+as `ans`.
+
+**IMPORTANT** : the `gradefn` function should not be at all asynchronous, since
+this could result in the student's latest answer not being passed correctly.
+Moreover, the function should also return promptly, since currently the student
+has no indication that her answer is being calculated/produced.
+
+******************************************************************************
+Option Attributes
+******************************************************************************
+
+The `height` and `width` attributes are straightforward: they specify the
+height and width of the iframe. Both are limited by the enclosing DOM elements,
+so for instance there is an implicit max-width of around 900. 
+
+In the future, JSInput may attempt to make these dimensions match the html
+file's dimensions (up to the aforementioned limits), but currently it defaults
+to `500` and `400` for `height` and `width`, respectively.
+
+==============================================================================
+set_statefn
+==============================================================================
+
+Sometimes a problem author will want information about a student's previous
+answers ("state") to be saved and reloaded. If the attribute `set_statefn` is
+used, the function given as its value will be passed the state as a string
+argument whenever there is a state, and the student returns to a problem. It is
+the responsibility of the function to then use this state approriately.
+
+The state that is passed is:
+
+1. The previous output of `gradefn` (i.e., the previous answer) if
+   `get_statefn` is not defined.
+2. The previous output of `get_statefn` (see below) otherwise.
+
+It is the responsibility of the iframe to do proper verification of the
+argument that it receives via `set_statefn`.
+
+==============================================================================
+get_statefn
+==============================================================================
+
+Sometimes the state and the answer are quite different. For instance, a problem
+that involves using a javascript program that allows the student to alter a
+molecule may grade based on the molecule's hidrophobicity, but from the
+hidrophobicity it might be incapable of restoring the state. In that case, a
+*separate* state may be stored and loaded by `set_statefn`. Note that if
+`get_statefn` is defined, the answer (i.e., what is passed to the enclosing
+response type) will be a json string with the following format::
+    {
+        answer: `[answer string]`
+        state: `[state string]`
+    }
+
+It is the responsibility of the enclosing response type to then parse this as
+json.

doc/public/index.rst

@@ -28,6 +28,7 @@ Specific Problem Types
    course_data_formats/conditional_module/conditional_module.rst
    course_data_formats/word_cloud/word_cloud.rst
    course_data_formats/custom_response.rst
+   course_data_formats/jsinput.rst
 
 
 Internal Data Formats