Release/v1.4.0: move frame documentation to this repo (#180)

* minimal demo of trying out sphinx-js and jsdoc for documentation rather than yuidoc * adding sections, don't extend fullscreen which base frame already extends * remove docs subrepo and framevideos to simplify maintenance; remove sphinx-js and rely just on manual rst files for now * remove sphinx_js extension * try displaying commit ID along with version * try READTHEDOCS key instead of readthedocs * just link to branch * fix link * move link to recent commits to sidebar * also commit sphinx-rtd-theme theme.conf * try defining theme_navigation_depth directly * actually import sphinx-rtd-theme! * try just using own fork of theme * remove custom template overrides * update theme * reference proper directory for theme subrepo * update theme * remove css changes for now - may add custom css rather than building from theme * update theme scss * fill in exp-lookit-video content, add a few stubs to link to, add custom css file * update theme, label branch * fix sidebar link formatting * rename submodule * add general overview and tabbed layout * minor fixes to (auto)docs * add most frames, remove unused next randomizer * finish adding standard frames (not yet randomizers, all mixins, deprecated frames) and remove jsdoc dependency * finish mixin docs, deprecated frame docs * finish adding randomizers and move some info over from lookit-docs * update links and add references * update docs * bump version and remove yuidoc dependencies * point to specific version of old docs for deprecated frames
lookit · Nov 7, 2020 · 5903255 · 5903255
1 parent e1eb458
commit 5903255
Show file tree

Hide file tree

Showing 101 changed files with 8,155 additions and 473 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -11,3 +11,5 @@ node_modules
 blueprints
 vendor
 helpers.js
+_build
+_themes
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,7 @@
 # compiled output
 /dist
 /tmp
+/_build
 
 # dependencies
 /node_modules
@@ -25,8 +26,6 @@ testem.log
 # Virtualenv
 scripts/env
 
-migration/output/*
-
 /ssl
 
 # tools

diff --git a/.gitmodules b/.gitmodules
@@ -1,3 +1,3 @@
-[submodule "docs"]
-	path = docs
-	url = https://github.com/lookit/lookit-frameplayer-docs.git
+[submodule "_themes/sphinx_rtd_theme"]
+	path = _themes/sphinx_rtd_theme
+	url = https://github.com/kimberscott/sphinx-rtd-theme-frameplayer
diff --git a/Makefile b/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = ./app
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/_styles/elf.css b/_styles/elf.css
@@ -0,0 +1,72 @@
+div.version {
+    margin-left: 1.5em;
+    color: gray;
+    margin-top: .5em;
+    margin-bottom: .5em;
+}
+
+nav#toggle-lookit-frameplayer ul {
+    list-style: none;
+    margin: 0;
+    padding: 0px;
+    margin-top: 2em;
+}
+
+nav#toggle-lookit-frameplayer li {
+    float: left;
+    border-bottom-width: 0;
+    border: thin solid whitesmoke;
+    padding: 10px 10px .5em 12px;
+    border-width: 1px 1px 0px 1px;
+    margin: 0 10px 0 0;
+    border-radius: 20px 8px 0px 0px;
+    background-color: #343131;
+}
+
+nav#toggle-lookit-frameplayer li a {
+    font-weight: bold;
+    color: #9a9a9a;
+}
+
+nav#toggle-lookit-frameplayer li a:visited  {
+    color: #9a9a9a;
+}
+
+#toggle-lookit-frameplayer #selected {
+    position: relative;
+    top: 1px;
+}
+
+#toggle-lookit-frameplayer #selected a, #toggle-lookit-frameplayer #selected a:visited {
+    color: white;
+}
+
+div.wy-side-nav-search {
+    clear: both;
+    display:inline-block;
+
+    border-bottom: thin solid whitesmoke;
+    margin-bottom: 0px !important;
+    padding-bottom: 0px !important;;
+}
+
+
+.wy-nav-side {
+    width: 20em;
+}
+
+.wy-side-scroll {
+    width: 22em;
+}
+
+.wy-side-nav-search {
+    width: 20em;
+}
+
+.wy-menu-vertical {
+    width: 20em;
+}
+
+.wy-nav-content-wrap {
+    margin-left: 20em;
+}
diff --git a/_themes/sphinx_rtd_theme b/_themes/sphinx_rtd_theme
diff --git a/app/components/exp-frame-base/component.js b/app/components/exp-frame-base/component.js
@@ -12,17 +12,13 @@ import SessionRecord from '../../mixins/session-record';
 
 /** An abstract component to extend when defining new Lookit frames
  *
- * This provides common base behavior required for any experiment frame. All experiment frames must extend this one.
+ * This provides common base behavior for all experiment frames.
  *
- * This frame has no configuration options because all of its logic is internal, and should not be directly used
- * in an experiment.
- *
- * As a user you will almost never need to insert a component into a template directly- the platform should handle that
+ * As a user you will almost never need to insert a component into a template directly - the platform should handle that
  *  by automatically inserting an <a href="../classes/Exp-player.html" class="crosslink">exp-player</a> component when your experiment starts.
- * However, a sample template usage is provided below for completeness.
  *
- * ```handlebars
- *  {{
+ * @example
+ {{
       component currentFrameTemplate
         frameIndex=frameIndex
         frameConfig=currentFrameConfig
@@ -37,14 +33,97 @@ import SessionRecord from '../../mixins/session-record';
         saveHandler=(action 'saveFrame')
         skipone=(action 'skipone')
         extra=extra
-    }}
- * ```
- * @class Exp-frame-base
+    }}``
+ *
+ * @class ExpFrameBase
+     * @param generateProperties{String} - Function to generate additional properties for this frame (like {"kind": "exp-lookit-text"})
+     * at the time the frame is initialized. Allows behavior of study to depend on what has
+     * happened so far (e.g., answers on a form or to previous test trials).
+     * Must be a valid Javascript function, returning an object, provided as
+     * a string.
+     *
+     *
+     * Arguments that will be provided are: `expData`, `sequence`, `child`, `pastSessions`, `conditions`.
+     *
+     *
+     * `expData`, `sequence`, and `conditions` are the same data as would be found in the session data shown
+     * on the Lookit experimenter interface under 'Individual Responses', except that
+     * they will only contain information up to this point in the study.
+     *
+     *
+     * `expData` is an object consisting of `frameId`: `frameData` pairs; the data associated
+     * with a particular frame depends on the frame kind.
+     *
+     *
+     * `sequence` is an ordered list of frameIds, corresponding to the keys in `expData`.
+     *
+     *
+     * `conditions` is an object representing the data stored by any randomizer frames;
+     * keys are `frameId`s for randomizer frames and data stored depends on the randomizer
+     * used.
+     *
+     *
+     * `child` is an object that has the following properties - use child.get(propertyName)
+     * to access:
+     * - `additionalInformation`: String; additional information field from child form
+     * - `ageAtBirth`: String; child's gestational age at birth in weeks. Possible values are
+     *   "24" through "39", "na" (not sure or prefer not to answer),
+     * "<24" (under 24 weeks), and "40>" (40 or more weeks).
+     * - `birthday`: Date object
+     * - `gender`: "f" (female), "m" (male), "o" (other), or "na" (prefer not to answer)
+     * - `givenName`: String, child's given name/nickname
+     * - `id`: String, child UUID
+     * - `languageList`: String, space-separated list of languages child is exposed to
+     * (2-letter codes)
+     * - `conditionList`: String, space-separated list of conditions/characteristics
+     * of child from registration form, as used in criteria expression, e.g.
+     * "autism_spectrum_disorder deaf multiple_birth"
+     *
+     *
+     * `pastSessions` is a list of previous response objects for this child and this study,
+     * ordered starting from most recent (at index 0 is this session!). Each has properties
+     * (access as pastSessions[i].get(propertyName)):
+     * - `completed`: Boolean, whether they submitted an exit survey
+     * - `completedConsentFrame`: Boolean, whether they got through at least a consent frame
+     * - `conditions`: Object representing any conditions assigned by randomizer frames
+     * - `createdOn`: Date object
+     * - `expData`: Object consisting of frameId: frameData pairs
+     * - `globalEventTimings`: list of any events stored outside of individual frames - currently
+     *   just used for attempts to leave the study early
+     * - `sequence`: ordered list of frameIds, corresponding to keys in expData
+     * - `isPreview`: Boolean, whether this is from a preview session (possible in the event
+     *   this is an experimenter's account)
+     *
+     *
+     * Example:
+     * ```
+     * function(expData, sequence, child, pastSessions, conditions) {
+     *     return {
+     *        'blocks':
+     *             [
+     *                 {
+     *                     'text': 'Name: ' + child.get('givenName')
+     *                 },
+     *                 {
+     *                     'text': 'Frame number: ' + sequence.length
+     *                 },
+     *                 {
+     *                     'text': 'N past sessions: ' + pastSessions.length
+     *                 }
+     *             ]
+     *       };
+     *   }
+     * ```
+     *
+     *
+     *  (This example is split across lines for readability; when added to JSON it would need
+     *  to be on one line.)
+
  *
  * @uses Full-screen
  * @uses Session-record
  */
-export default Ember.Component.extend(FullScreen, SessionRecord, {
+let ExpFrameBase = Ember.Component.extend(FullScreen, SessionRecord, {
     toast: Ember.inject.service(),
     // {String} the unique identifier for the _instance_
     id: null,
@@ -116,7 +195,7 @@ export default Ember.Component.extend(FullScreen, SessionRecord, {
      * - `languageList`: String, space-separated list of languages child is exposed to
      * (2-letter codes)
      * - `conditionList`: String, space-separated list of conditions/characteristics
-     * - of child from registration form, as used in criteria expression, e.g.
+     * of child from registration form, as used in criteria expression, e.g.
      * "autism_spectrum_disorder deaf multiple_birth"
      *
      *
@@ -552,11 +631,7 @@ export default Ember.Component.extend(FullScreen, SessionRecord, {
         },
 
         next() {
-            /**
-             * Move to next frame
-             *
-             * @event nextFrame
-             */
+
             this.send('setTimeEvent', 'nextFrame');
 
             // Determine which frame to go to next
@@ -652,3 +727,5 @@ export default Ember.Component.extend(FullScreen, SessionRecord, {
         this._super(...arguments);
     }
 });
+
+export default ExpFrameBase;