chore: Add Teak xml directory

release-scripts/toggles-diffs/README.rst

@@ -4,5 +4,7 @@ README
 A folder that holds scripts to generate the diffs in toggles and settings between arbitrary releases.
 
 * ``sumac-xml``: The ``_build/xml`` directory from the edx-platform docs build for the Sumac release.
-  Note in this folder, the XML needed for the diff scripts is: ``sumac-xml/references/featuretoggles.xml`` and ``sumac-xml/references/settings.xml``
-  This path is the same for pre-Sumac releases, but has changed in Teak.
+
+* ``teak-xml``: The ``_build/xml`` directory from the edx-platform docs build for the Sumac release.
+
+For the xml directories, the needed files are in the ``releasename-xml/references`` directory.

release-scripts/toggles-diffs/teak-xml/_sphinx_design_static/design-tabs.js

@@ -0,0 +1,101 @@
+// @ts-check
+
+// Extra JS capability for selected tabs to be synced
+// The selection is stored in local storage so that it persists across page loads.
+
+/**
+ * @type {Record<string, HTMLElement[]>}
+ */
+let sd_id_to_elements = {};
+const storageKeyPrefix = "sphinx-design-tab-id-";
+
+/**
+ * Create a key for a tab element.
+ * @param {HTMLElement} el - The tab element.
+ * @returns {[string, string, string] | null} - The key.
+ *
+ */
+function create_key(el) {
+  let syncId = el.getAttribute("data-sync-id");
+  let syncGroup = el.getAttribute("data-sync-group");
+  if (!syncId || !syncGroup) return null;
+  return [syncGroup, syncId, syncGroup + "--" + syncId];
+}
+
+/**
+ * Initialize the tab selection.
+ *
+ */
+function ready() {
+  // Find all tabs with sync data
+
+  /** @type {string[]} */
+  let groups = [];
+
+  document.querySelectorAll(".sd-tab-label").forEach((label) => {
+    if (label instanceof HTMLElement) {
+      let data = create_key(label);
+      if (data) {
+        let [group, id, key] = data;
+
+        // add click event listener
+        // @ts-ignore
+        label.onclick = onSDLabelClick;
+
+        // store map of key to elements
+        if (!sd_id_to_elements[key]) {
+          sd_id_to_elements[key] = [];
+        }
+        sd_id_to_elements[key].push(label);
+
+        if (groups.indexOf(group) === -1) {
+          groups.push(group);
+          // Check if a specific tab has been selected via URL parameter
+          const tabParam = new URLSearchParams(window.location.search).get(
+            group
+          );
+          if (tabParam) {
+            console.log(
+              "sphinx-design: Selecting tab id for group '" +
+                group +
+                "' from URL parameter: " +
+                tabParam
+            );
+            window.sessionStorage.setItem(storageKeyPrefix + group, tabParam);
+          }
+        }
+
+        // Check is a specific tab has been selected previously
+        let previousId = window.sessionStorage.getItem(
+          storageKeyPrefix + group
+        );
+        if (previousId === id) {
+          // console.log(
+          //   "sphinx-design: Selecting tab from session storage: " + id
+          // );
+          // @ts-ignore
+          label.previousElementSibling.checked = true;
+        }
+      }
+    }
+  });
+}
+
+/**
+ *  Activate other tabs with the same sync id.
+ *
+ * @this {HTMLElement} - The element that was clicked.
+ */
+function onSDLabelClick() {
+  let data = create_key(this);
+  if (!data) return;
+  let [group, id, key] = data;
+  for (const label of sd_id_to_elements[key]) {
+    if (label === this) continue;
+    // @ts-ignore
+    label.previousElementSibling.checked = true;
+  }
+  window.sessionStorage.setItem(storageKeyPrefix + group, id);
+}
+
+document.addEventListener("DOMContentLoaded", ready, false);

release-scripts/toggles-diffs/teak-xml/concepts/frontend/bootstrap.xml

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">
+<!-- Generated by Docutils 0.21.2 -->
+<document source="/Users/sarinacanelake/openedx/edx-platform/docs/concepts/frontend/bootstrap.rst" translation_progress="{'total': 0, 'translated': 0}" xmlns:c="https://www.sphinx-doc.org/" xmlns:changeset="https://www.sphinx-doc.org/" xmlns:citation="https://www.sphinx-doc.org/" xmlns:cpp="https://www.sphinx-doc.org/" xmlns:http="https://www.sphinx-doc.org/" xmlns:index="https://www.sphinx-doc.org/" xmlns:js="https://www.sphinx-doc.org/" xmlns:math="https://www.sphinx-doc.org/" xmlns:py="https://www.sphinx-doc.org/" xmlns:rst="https://www.sphinx-doc.org/" xmlns:std="https://www.sphinx-doc.org/">
+    <target refid="ui-bootstrap"></target>
+    <section ids="working-with-bootstrap ui-bootstrap" names="working\ with\ bootstrap ui_bootstrap">
+        <title>Working with Bootstrap</title>
+        <paragraph>This topic describes the Bootstrap framework, and how it should be used to
+            build user interfaces within edX applications. Note that Bootstrap adoption
+            started after the Ginkgo release, and so this document applies to the edX
+            master branch and to the forthcoming Hawthorn release.</paragraph>
+        <paragraph>If you are interested in the rationale for edX choosing Bootstrap, you can
+            read about the decision in <reference name="OEP-16: Adopting Bootstrap" refuri="https://open-edx-proposals.readthedocs.io/en/latest/oep-0016-bp-adopt-bootstrap.html">OEP-16: Adopting Bootstrap</reference><target ids="oep-16-adopting-bootstrap" names="oep-16:\ adopting\ bootstrap" refuri="https://open-edx-proposals.readthedocs.io/en/latest/oep-0016-bp-adopt-bootstrap.html"></target>.</paragraph>
+        <section ids="getting-started" names="getting\ started">
+            <title>Getting Started</title>
+            <paragraph>Bootstrap is an open source front end component library that is used by many of
+                the world’s most popular applications. It allows for rapid assembly of front end
+                components using a responsive grid system, a robust component library and easy
+                to configure theming capabilities to ensure that new components are rendered
+                consistently. EdX is using <reference name="Bootstrap 4" refuri="https://getbootstrap.com/docs/4.0/getting-started/introduction/">Bootstrap 4</reference> which is a reimplemented version using
+                Sass and that is currently in beta release.</paragraph>
+            <paragraph>All edX applications should use the <reference name="edx-bootstrap" refuri="https://www.npmjs.com/package/@edx/edx-bootstrap">edx-bootstrap</reference> package that can be
+                installed via <reference name="npm" refuri="https://www.npmjs.com/">npm</reference>. This package provides two themes (a default Open edX
+                theme, as well as an edX branded version), and eventually will provide custom
+                Open edX styles for common patterns.</paragraph>
+            <target refid="ui-bootstrap-custom-designs"></target>
+        </section>
+        <section ids="developing-custom-designs ui-bootstrap-custom-designs" names="developing\ custom\ designs ui_bootstrap_custom_designs">
+            <title>Developing Custom Designs</title>
+            <paragraph>Bootstrap provides a large number of components and layouts out-of-the-box, but
+                there will always be a need to implement custom designs. There are a number of
+                considerations to take into account when implementing your designs using Sass.</paragraph>
+            <paragraph>The most important rule is to avoid hard-coding values such as colors and fonts.
+                Using hard-coded values means that Bootstrap themes will not be able to affect
+                your styles, and so your new elements will look out of place. Whenever possible
+                you should instead use the functions and variables provided by Bootstrap to
+                access theme colors or fonts. See <reference name="Bootstrap customization options" refuri="https://getbootstrap.com/docs/4.0/getting-started/options/">Bootstrap customization options</reference> for more
+                details.</paragraph>
+            <paragraph>For example, here is an example of a hard-coded style:</paragraph>
+            <literal_block force="False" language="none" linenos="False" xml:space="preserve">.my-element {
+  font-family: "Open Sans";
+  color: #0000ff;
+}</literal_block>
+            <paragraph>The recommended alternative is as follows:</paragraph>
+            <literal_block force="False" language="none" linenos="False" xml:space="preserve">.my-element {
+  font-family: $font-family-sans-serif;
+  color: theme-color("primary");
+}</literal_block>
+            <paragraph>If you do find the need for a custom color or font that isn’t provided by
+                the edX Bootstrap library, consider first whether it makes sense to contribute
+                it back so that other applications can use this value too. If you decide to
+                add a custom value, define it as a variable that can be overridden by a theme by
+                using the <literal>!default</literal> flag. This allows themes to provide a different value
+                for this variable if they choose. See the Sass documentation for <reference name="default flag" refuri="http://sass-lang.com/documentation/file.SASS_REFERENCE.html#Variable_Defaults___default">default flag</reference>
+                for more details.</paragraph>
+            <paragraph>For example:</paragraph>
+            <literal_block force="False" language="none" linenos="False" xml:space="preserve">$my-custom-color: #0000ff !default;
+
+.my-element {
+  font-family: $font-family-sans-serif;
+  color: $my-custom-color;
+}</literal_block>
+            <target ids="bootstrap-4" names="bootstrap\ 4" refuri="https://getbootstrap.com/docs/4.0/getting-started/introduction/"></target>
+            <target ids="bootstrap-customization-options" names="bootstrap\ customization\ options" refuri="https://getbootstrap.com/docs/4.0/getting-started/options/"></target>
+            <target ids="default-flag" names="default\ flag" refuri="http://sass-lang.com/documentation/file.SASS_REFERENCE.html#Variable_Defaults___default"></target>
+            <target ids="edx-bootstrap" names="edx-bootstrap" refuri="https://www.npmjs.com/package/@edx/edx-bootstrap"></target>
+            <target ids="npm" names="npm" refuri="https://www.npmjs.com/"></target>
+        </section>
+    </section>
+</document>

release-scripts/toggles-diffs/teak-xml/concepts/frontend/javascript.xml

@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">
+<!-- Generated by Docutils 0.21.2 -->
+<document source="/Users/sarinacanelake/openedx/edx-platform/docs/concepts/frontend/javascript.rst" translation_progress="{'total': 0, 'translated': 0}" xmlns:c="https://www.sphinx-doc.org/" xmlns:changeset="https://www.sphinx-doc.org/" xmlns:citation="https://www.sphinx-doc.org/" xmlns:cpp="https://www.sphinx-doc.org/" xmlns:http="https://www.sphinx-doc.org/" xmlns:index="https://www.sphinx-doc.org/" xmlns:js="https://www.sphinx-doc.org/" xmlns:math="https://www.sphinx-doc.org/" xmlns:py="https://www.sphinx-doc.org/" xmlns:rst="https://www.sphinx-doc.org/" xmlns:std="https://www.sphinx-doc.org/">
+    <section ids="javascript-in-edx-platform" names="javascript\ in\ edx-platform">
+        <title>JavaScript in edx-platform</title>
+        <paragraph>All frontend code (JavaScript) has been deprecated in edx-platform, in favor of
+            MFEs. See ADR 0023-frontend-code-and-eslint-removal.rst for details.</paragraph>
+        <paragraph>This documentation is being left in place until all of the JavaScript code
+            has been removed.</paragraph>
+        <section ids="es2015" names="es2015">
+            <title>ES2015</title>
+            <paragraph>All JavaScript code in edx-platform should be written in ES2015.
+                ES2015 is not a framework or library – rather, it is the latest and
+                greatest revision of the JavaScript language itself, natively supported
+                in all modern browsers and engines. Think of it as JavaScript’s
+                equivalent to Python 3. ES2015 brings with it number of wonderful
+                syntactic features, such as classes, native imports, arrow functions,
+                and new data structures. To learn more about ES2015, check out <reference name="Luke Hoban's comprehensive ES6 Features repo" refuri="https://github.com/lukehoban/es6features">Luke
+                    Hoban’s comprehensive ES6 Features
+                    repo</reference>.</paragraph>
+            <paragraph>Although ES2015 is natively supported in modern browsers, older browsers
+                can’t interpret it. Here at edX, we support the two latest versions of
+                every browser, plus IE11, so we need to do a little extra work to
+                support ES2015. This is where Webpack and Babel come in. Webpack is a
+                module bundler that transforms, minifies, and compiles frontend code
+                into pre-built “bundles” to include within pages. It works together with
+                Babel to transpile ES2015 code into ES5 code, which can safely be used
+                in all browsers.</paragraph>
+            <paragraph>Fortunately, you don’t need to worry about the gritty details of Webpack
+                in order to write ES2015 code. You just need to make sure Webpack knows
+                where to find your files. It’s also important to note that <strong>Webpack is
+                    not compatible with RequireJS</strong>. Work is currently underway to move all
+                legacy RequireJS modules into Webpack, but until it is complete, you
+                will need to update legacy code yourself in order to use it with ES2015.</paragraph>
+            <section ids="adding-a-new-es2015-module" names="adding\ a\ new\ es2015\ module">
+                <title>Adding a New ES2015 Module</title>
+                <paragraph>Don’t mix ES2015 and ES5 modules within directories. If necessary,
+                    create a new directory just for your new file.</paragraph>
+                <paragraph>Give your new file an UpperCamelCase filename, such as
+                    <literal>MyAwesomeModule.js</literal>. If it is a React module, use the <literal>.jsx</literal>
+                    extension; otherwise, use the <literal>.js</literal> extension.</paragraph>
+                <paragraph>If you intend to include this module itself directly within a page, you
+                    will need to tell Webpack about it. Add a line to the <literal>entry</literal> object
+                    within <literal>webpack.common.config.js</literal>.</paragraph>
+                <literal_block force="False" language="default" linenos="False" xml:space="preserve">'MyAwesomeModule': 'path/to/your/directory/MyAwesomeModule.js',</literal_block>
+                <paragraph>The new entry’s key should be the name of your module (typically this is
+                    the same as your filename), and its value should be the path to your
+                    file relative to the edx-platform root.</paragraph>
+            </section>
+            <section ids="writing-your-file" names="writing\ your\ file">
+                <title>Writing Your File</title>
+                <paragraph>Structure your module using <literal>class</literal>es. Typically, you’ll want to
+                    define and export one <literal>class</literal> per file. If you are going to be
+                    including this module directly within a page and passing it through
+                    Webpack, use a non-default export. <literal>MyAwesomeModule.js</literal> should look
+                    something like this:</paragraph>
+                <literal_block force="False" language="default" linenos="False" xml:space="preserve">export class MyAwesomeModule {
+  // your awesome code here
+}</literal_block>
+                <paragraph>Use two-space indentation. This is industry standard practice for
+                    ES2015. If you need to pull in external dependencies, use <literal>import</literal>
+                    statements:</paragraph>
+                <literal_block force="False" language="default" linenos="False" xml:space="preserve">import moment from 'moment';
+import 'jquery.cookie';
+import { MyOtherModule } from './MyOtherModule';</literal_block>
+            </section>
+            <section ids="building-your-file" names="building\ your\ file">
+                <title>Building Your File</title>
+                <paragraph>Devstack comes with two watcher containers specifically for building
+                    assets. They compile frontend files very quickly, so you can see your
+                    changes reflected in a browser almost immediately. You can run these
+                    containers with:</paragraph>
+                <literal_block force="False" language="default" linenos="False" xml:space="preserve">make dev.up.watchers</literal_block>
+                <paragraph>and stop them with</paragraph>
+                <literal_block force="False" language="default" linenos="False" xml:space="preserve">make stop.watchers</literal_block>
+                <paragraph>If you make any changes to <literal>webpack.common.config.js</literal> while the
+                    watchers are running, you will need to restart the watchers in order for
+                    them to pick up your changes.</paragraph>
+                <paragraph>If your changes aren’t being reflected in the browser, check the logs
+                    with <literal>make logs</literal> to see if something went wrong. If you get stuck, ask
+                    for help in the FedX hipchat room, or in #front-end on Slack.</paragraph>
+            </section>
+        </section>
+    </section>
+</document>