Merge pull request #17121 from edx/ari/frontend-docs

first pass JS and Bootstrap docs

docs/bootstrap.rst

@@ -0,0 +1,88 @@
+..  _ui_bootstrap:
+
+######################
+Working with Bootstrap
+######################
+
+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.
+
+If you are interested in the rationale for edX choosing Bootstrap, you can
+read about the decision in `OEP-16: Adopting Bootstrap
+<https://open-edx-proposals.readthedocs.io/en/latest/oep-0016.html>`_.
+
+.. highlight:: none
+
+***************
+Getting Started
+***************
+
+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 `Bootstrap 4`_ which is a reimplemented version using
+Sass and that is currently in beta release.
+
+All edX applications should use the `edx-bootstrap`_ package that can be
+installed via `npm`_. 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.
+
+..  _ui_bootstrap_custom_designs:
+
+*************************
+Developing Custom Designs
+*************************
+
+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.
+
+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 `Bootstrap customization options`_ for more
+details.
+
+For example, here is an example of a hard-coded style::
+
+    .my-element {
+      font-family: "Open Sans";
+      color: #0000ff;
+    }
+
+The recommended alternative is as follows::
+
+    .my-element {
+      font-family: $font-family-sans-serif;
+      color: theme-color("primary");
+    }
+
+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 ``!default`` flag. This allows themes to provide a different value
+for this variable if they choose. See the Sass documentation for `default flag`_
+for more details.
+
+For example::
+
+    $my-custom-color: #0000ff !default;
+
+    .my-element {
+      font-family: $font-family-sans-serif;
+      color: $my-custom-color;
+    }
+
+
+
+.. _Bootstrap 4: https://getbootstrap.com/docs/4.0/getting-started/introduction/
+.. _Bootstrap customization options: https://getbootstrap.com/docs/4.0/getting-started/options/
+.. _default flag: http://sass-lang.com/documentation/file.SASS_REFERENCE.html#Variable_Defaults___default
+.. _edx-bootstrap: https://www.npmjs.com/package/@edx/edx-bootstrap
+.. _npm: https://www.npmjs.com/

docs/javascript.rst

@@ -0,0 +1,110 @@
+JavaScript in edx-platform
+==========================
+
+ES2015
+------
+
+All new 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 `Luke
+Hoban's comprehensive ES6 Features
+repo <https://github.com/lukehoban/es6features>`__.
+
+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.
+
+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 **Webpack is
+not compatible with RequireJS**. 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.
+
+Adding a New ES2015 Module
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Don't mix ES2015 and ES5 modules within directories. If necessary,
+create a new directory just for your new file. If you create a new
+directory, run the following from edx-platform root to copy over an
+appropriate eslint config:
+
+::
+
+    cp cms/static/js/features_jsx/.eslintrc.js path/to/your/directory
+
+Give your new file an UpperCamelCase filename, such as
+``MyAwesomeModule.js``. If it is a React module, use the ``.jsx``
+extension; otherwise, use the ``.js`` extension.
+
+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 ``entry`` object
+within ``webpack.common.config.js``.
+
+::
+
+    'MyAwesomeModule': 'path/to/your/directory/MyAwesomeModule.js',
+
+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.
+
+Writing Your File
+~~~~~~~~~~~~~~~~~
+
+Structure your module using ``class``\ es. Typically, you'll want to
+define and export one ``class`` 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. ``MyAwesomeModule.js`` should look
+something like this:
+
+::
+
+    export class MyAwesomeModule {
+      // your awesome code here
+    }
+
+Use two-space indentation. This is industry standard practice for
+ES2015. If you need to pull in external dependencies, use ``import``
+statements:
+
+::
+
+    import moment from 'moment';
+    import 'jquery.cookie';
+    import { MyOtherModule } from './MyOtherModule';
+
+Building Your File
+~~~~~~~~~~~~~~~~~~
+
+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:
+
+::
+
+    make dev.up.watchers
+
+and stop them with
+
+::
+
+    make stop.watchers
+
+If you make any changes to ``webpack.common.config.js`` while the
+watchers are running, you will need to restart the watchers in order for
+them to pick up your changes.
+
+If your changes aren't being reflected in the browser, check the logs
+with ``make logs`` to see if something went wrong. If you get stuck, ask
+for help in the FedX hipchat room, or in #front-end on Slack.