Update docs template (#412)

* comment out notes in JS code blocks (prevents build errors and improves syntax highlighting) * remove custom RTD theme and replace with template override with docs tabs * update project title * update python requirements * add docs JS file for opening external links in new tab and update file structure to match lookit-docs
lookit · Nov 18, 2024 · 7d0fb7e · 7d0fb7e
1 parent 778a3cb
commit 7d0fb7e
Show file tree

Hide file tree

Showing 9 changed files with 259 additions and 169 deletions.
diff --git a/_styles/elf.css → _static/css/elf.css b/_styles/elf.css → _static/css/elf.css
@@ -1,3 +1,9 @@
+img {
+    border: thin solid gray !important;
+    box-shadow: 3px 3px 3px #ccc;
+    margin-bottom: 1em;
+}
+
 div.version {
     margin-left: 1.5em;
     color: gray;
@@ -18,7 +24,7 @@ nav#toggle-lookit-frameplayer li {
     border: thin solid whitesmoke;
     padding: 10px 10px .5em 12px;
     border-width: 1px 1px 0px 1px;
-    margin: 0 10px 0 0;
+    margin: 0;
     border-radius: 20px 8px 0px 0px;
     background-color: #343131;
 }

diff --git a/_static/js/links_in_new_tab.js b/_static/js/links_in_new_tab.js
@@ -0,0 +1,3 @@
+$(document).ready(function () {
+    $('a[href^="http://"], a[href^="https://"]').not('a[class*=internal]').attr('target', '_blank');
+ });
diff --git a/_templates/layout.html b/_templates/layout.html
@@ -0,0 +1,59 @@
+{%- extends "!layout.html" %}
+
+{% block sidebartitle %}
+
+    {# From the sphinx-rtd-theme layout: https://github.com/simonw/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html #}
+
+    {% if logo and theme_logo_only %}
+        <a href="{{ theme_logo_url or pathto(master_doc) }}">
+    {% else %}
+        <a href="{{ theme_logo_url or pathto(master_doc) }}" class="icon icon-home"> {{ project }}
+    {% endif %}
+
+    {% if logo %}
+        {# Not strictly valid HTML, but it's the only way to display/scale
+            it properly, without weird scripting or heaps of work
+        #}
+        <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
+    {% endif %}
+    </a>
+
+    {% if theme_display_version %}
+        {%- set nav_version = version %}
+        {% if READTHEDOCS and current_version %}
+            {%- set nav_version = current_version %}
+        {% endif %}
+        {% if nav_version %}
+            <div class="version">
+            {{ nav_version }}
+            </div>
+        {% endif %}
+    {% endif %}
+
+    {% include "searchbox.html" %}
+
+    {# From Kim's forked RTD theme: https://github.com/kimberscott/sphinx-rtd-theme-frameplayer #}
+    <div id="toggle-tab-container" style="position: relative;">
+        <nav id="toggle-lookit-frameplayer">
+            <ul>
+                <li><a href="https://lookit.readthedocs.io" class="icon icon-home"> CHS </a></li>
+                <li id="selected">
+                    {% if logo and theme_logo_only %}
+                    <a href="{{ pathto(master_doc) }}">
+                        {% else %}
+                        <a href="{{ pathto(master_doc) }}" class="fa fa-puzzle-piece"> Lookit EFP
+                        {% endif %}
+                        {% if logo %}
+                        {# Not strictly valid HTML, but it's the only way to display/scale
+                        it properly, without weird scripting or heaps of work
+                        #}
+                        <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
+                        {% endif %}
+                    </a>
+                </li>
+                <li><a href="https://lookit.readthedocs.io/projects/chs-jspsych/" class="fa fa-puzzle-piece"> jsPsych </a></li>
+            </ul>
+        </nav>
+    </div>
+
+{% endblock %}
diff --git a/_themes/sphinx_rtd_theme b/_themes/sphinx_rtd_theme
diff --git a/app/components/exp-lookit-calibration/doc.rst b/app/components/exp-lookit-calibration/doc.rst
@@ -269,24 +269,24 @@ rename ``calibrationAudioSources`` and ``calibrationVideoSources``, and remove t
 .. code:: javascript
 
     "sample-physics-calibration": {
-        "kind": "exp-lookit-calibration", <-- change the "kind"
-        "baseDir": "https://www.mit.edu/~kimscott/placeholderstimuli/", <-- leave this the same
-        "audioTypes": [ <-- leave this the same
+        "kind": "exp-lookit-calibration", // <--  change the "kind"
+        "baseDir": "https://www.mit.edu/~kimscott/placeholderstimuli/", // <--  leave this the same
+        "audioTypes": [ // <--  leave this the same
             "ogg",
             "mp3"
         ],
-        "videoTypes": [ <-- leave this the same
+        "videoTypes": [ // <--  leave this the same
             "webm",
             "mp4"
         ],
 
-        "calibrationLength": 3000,  <-- leave this the same
-        "calibrationAudio": "chimes",  <-- just rename from "calibrationAudioSources"
-        "calibrationVideo": "attentiongrabber",  <-- just rename from "calibrationVideoSources"
+        "calibrationLength": 3000,  // <--  leave this the same
+        "calibrationAudio": "chimes",  // <--  just rename from "calibrationAudioSources"
+        "calibrationVideo": "attentiongrabber",  // <--  just rename from "calibrationVideoSources"
 
-        "pauseAudio": "pause", <-- leave these the same
+        "pauseAudio": "pause", // <--  leave these the same
         "unpauseAudio": "return_after_pause",
-        "pauseVideo": "attentiongrabber" <-- just rename from "attnSources"
+        "pauseVideo": "attentiongrabber" // <--  just rename from "attnSources"
     }
 
 If your old frame defined ``calibrationPositions``, you can leave that the same too. Otherwise this will continue to
@@ -341,22 +341,22 @@ You can change it to an ``exp-lookit-calibration`` frame just by changing the ``
 .. code:: javascript
 
     "sample-trial": {
-        "kind": "exp-lookit-calibration", <-- change the "kind"
-        "baseDir": "https://s3.amazonaws.com/lookitcontents/labelsconcepts/", <-- leave this the same
-        "audioTypes": [ <-- leave this the same
+        "kind": "exp-lookit-calibration", // <--  change the "kind"
+        "baseDir": "https://s3.amazonaws.com/lookitcontents/labelsconcepts/", // <--  leave this the same
+        "audioTypes": [ // <--  leave this the same
             "ogg",
             "mp3"
         ],
-        "videoTypes": [ <-- leave this the same
+        "videoTypes": [ // <--  leave this the same
             "webm",
             "mp4"
         ],
 
-        "calibrationLength": 0, <-- leave this the same
-        "calibrationAudio": "chimes", <-- leave this the same
-        "calibrationVideo": "attentiongrabber", <-- leave this the same
+        "calibrationLength": 0, // <--  leave this the same
+        "calibrationAudio": "chimes", // <--  leave this the same
+        "calibrationVideo": "attentiongrabber", // <--  leave this the same
 
-        "pauseAudio": "pause", <-- leave these the same
+        "pauseAudio": "pause", // <--  leave these the same
         "unpauseAudio": "return_after_pause",
-        "pauseVideo": "attentiongrabber" <-- copy this from announcementVideo
+        "pauseVideo": "attentiongrabber" // <--  copy this from announcementVideo
     }
diff --git a/app/components/exp-lookit-images-audio/doc.rst b/app/components/exp-lookit-images-audio/doc.rst
@@ -676,13 +676,13 @@ To create the test trial portion as an exp-lookit-images-audio frame, we will:
    .. code:: javascript
 
         "test-trial": {
-            "kind": "exp-lookit-images-audio", <-- update the "kind"
-            "baseDir": "https://s3.amazonaws.com/lookitcontents/labelsconcepts/", <-- keep this the same
-            "audioTypes": [ <-- keep this the same
+            "kind": "exp-lookit-images-audio", // <-- update the "kind"
+            "baseDir": "https://s3.amazonaws.com/lookitcontents/labelsconcepts/", // <-- keep this the same
+            "audioTypes": [ // <-- keep this the same
                 "ogg",
                 "mp3"
             ],
-            "videoTypes": [ <-- keep this the same
+            "videoTypes": [ // <-- keep this the same
                 "webm",
                 "mp4"
             ],
@@ -700,17 +700,17 @@ To create the test trial portion as an exp-lookit-images-audio frame, we will:
             ...
             "images": [
                 {
-                    "id": "left" <-- you can actually name this whatever you want
+                    "id": "left", // <-- you can actually name this whatever you want
                     "src": "stapler_test_02.jpg", <-- "leftImage"
                     "position": "left"
                 },
                 {
-                    "id": "right" <-- you can actually name this whatever you want
-                    "src": "novel_02.jpg", <-- "rightImage"
+                    "id": "right", // <-- you can actually name this whatever you want
+                    "src": "novel_02.jpg", // <-- "rightImage"
                     "position": "right"
                 }
             ],
-            "audio": "400Hz_tones" <-- "testAudio"
+            "audio": "400Hz_tones" // <-- "testAudio"
         }
 
    Note that it is not yet possible to make the audio loop. If you need audio to loop, for now please create a version
@@ -726,17 +726,17 @@ To create the test trial portion as an exp-lookit-images-audio frame, we will:
             ...
             "images": [
                 {
-                    "id": "left" <-- you can actually name this whatever you want
-                    "src": "POSSIBLEIMAGES#1", <-- "POSSIBLEIMAGES#leftImageIndex
+                    "id": "left", // <-- you can actually name this whatever you want
+                    "src": "POSSIBLEIMAGES#1", // <-- "POSSIBLEIMAGES#leftImageIndex
                     "position": "left"
                 },
                 {
-                    "id": "right" <-- you can actually name this whatever you want
-                    "src": "POSSIBLEIMAGES#0", <-- "POSSIBLEIMAGES#rightImageIndex
+                    "id": "right", // <-- you can actually name this whatever you want
+                    "src": "POSSIBLEIMAGES#0", // <-- "POSSIBLEIMAGES#rightImageIndex
                     "position": "right"
                 }
             ],
-            "audio": "400Hz_tones" <-- "testAudio",
+            "audio": "400Hz_tones", // <-- "testAudio",
             "parameters": {
                 "POSSIBLEIMAGES": ["novel_02.jpg", "stapler_test_02.jpg"]
             }