[docs] update example nbextension

 * to use example CSS file
 * to use simpler config loading mechanism

[skip CI]

Author: jcb91

README.md

@@ -231,14 +231,17 @@ See also [installing Jupyter](https://jupyter.readthedocs.io/en/latest/install.h
 Notebook extension structure
 ============================
 
-The nbextensions are stored each as a separate subdirectory of `src/jupyter_contrib_nbextensions/nbextensions`
-Each notebook extension typically has it's own directory containing:
+The nbextensions are stored in the repository each as a separate subdirectory of
+`src/jupyter_contrib_nbextensions/nbextensions`.
 
- * `thisextension/main.js` - javascript implementing the extension
- * `thisextension/main.css` - optional CSS
- * `thisextension/readme.md` - readme file describing the extension in markdown format
- * `thisextension/config.yaml` - file describing the extension to the `jupyter_nbextensions_configurator` server extension
+Each notebook extension typically has its own directory named after the extension, containing:
 
+ * `thisextension/thisextension.js` - javascript implementing the nbextension
+ * `thisextension/thisextension.yml` - file describing the nbextension to the `jupyter_nbextensions_configurator` server extension
+ * `thisextension/thisextension.css` - optional CSS file, which may be loaded by the javascript
+ * `thisextension/README.md` - readme file describing the nbextension in markdown format
+
+For further details, see [the documentation at jupyter-contrib-nbextensions.readthedocs.io](http://jupyter-contrib-nbextensions.readthedocs.io/en/latest/internals.html).
 
 Changes
 =======

docs/source/internals.rst

@@ -3,31 +3,29 @@
 Notebook extension structure
 ============================
 
-The nbextensions are stored each as a separate subdirectory of
-`src/jupyter_contrib_nbextensions/nbextensions`
+The nbextensions are stored in the repository each as a separate subdirectory of
+`src/jupyter_contrib_nbextensions/nbextensions`.
 
-Each notebook extension typically has its own directory containing:
+Each notebook extension typically has its own directory named after the extension, containing:
 
-* `thisextension/main.js`: javascript implementing the nbextension
-* `thisextension/main.css`: optional CSS
-* `thisextension/readme.md`: readme file describing the nbextension in markdown format
-* `thisextension/config.yaml`: file describing the nbextension to the `jupyter_nbextensions_configurator` server extension
+ * `thisextension/thisextension.js` - javascript implementing the nbextension
+ * `thisextension/thisextension.yml` - file describing the nbextension to the `jupyter_nbextensions_configurator` server extension
+ * `thisextension/thisextension.css` - optional CSS file, which may be loaded by the javascript
+ * `thisextension/README.md` - readme file describing the nbextension in markdown format
 
-The file names do not need to have the shown names, they can be choosen freely.
-This is an example for the `main.js` file:
+The file names do not need to have the shown names, they can be chosen freely, as long as they refer to each other using the appropriate names.
+This is an example for the main `thisextension.js` file:
 
 .. code-block:: javascript
 
     define([
+        'require',
         'jquery',
         'base/js/namespace',
-        'base/js/utils',
-        'services/config'
     ], function (
+        requirejs
         $,
-        IPython,
-        utils,
-        configmod,
+        Jupyter,
     ) {
         "use strict";
 
@@ -36,74 +34,90 @@ This is an example for the `main.js` file:
             my_config_value : 100
         };
 
-        // create config object to load parameters
-        var base_url = utils.get_body_data("baseUrl");
-        var config = new configmod.ConfigSection('notebook', {base_url: base_url});
-
-        // update params with any specified in the server's config file
-        var update_params = function() {
-            for (var key in params) {
-                if (config.data.hasOwnProperty(key))
-                    params[key] = config.data[key];
-            }
-        };
-
-        // will be called when the config parameters have been loaded
-        config.loaded.then( function() {
-            update_params();
-
-        });
-
-        function config_loaded_callback () {
-            $.extend(true, params, config.data.thisextension);
+        var initialize = function () {
+            // update params with any specified in the server's config file.
+            // the "thisextension" value of the Jupyter notebook config's
+            // data may be undefined, but that's ok when using JQuery's extend
+            $.extend(true, params, Jupyter.notebook.config.thisextension);
+
+            // add our extension's css to the page
+            $('<link/>')
+                .attr({
+                    rel: 'stylesheet',
+                    type: 'text/css',
+                    href: requirejs.toUrl('./thisextension.css')
+                })
+                .appendTo('head');
         };
 
-        // will be called when the nbextension is loaded
+        // The specially-named function load_ipython_extension will be called
+        // by the notebook when the nbextension is to be loaded.
+        // It mustn't take too long to execute however, or the notebook will
+        // assume an error has occurred.
         var load_ipython_extension = function () {
-            config.load(); // trigger loading config parameters
-
+            // Once the config has been loaded, do everything else.
+            // The loaded object is a javascript Promise object, so the then
+            // call return immediately. See
+            // https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
+            // for details.
+            return Jupyter.notebook.config.loaded.then(initialize);
         };
 
-        // return public methods
+        // return object to export public methods
         return {
-            load_jupyter_extension : load_jupyter_extension
+            load_ipython_extension : load_ipython_extension
         };
     });
 
-And for the `config.yaml` file:
+And for the `thisextension.yml` file:
 
 .. code-block:: yaml
 
     Type: Jupyter Notebook Extension
-    Compatibility: 4.x
-    Name: thisextension
-    Main: main.js
+    Compatibility: 4.x, 5.x
+    Name: This Extension
+    Main: thisextension.js
     Icon: icon.png
     Link: README.md
     Description: My super duper extension
     Parameters:
-    - name: my_config_value
-      description: A configuration parameter
+    - name: thisextension.my_config_value
+      description: Number of dupers to create
       input_type: number
       min: -1
       step: 1
       default: 100
 
-When supplying a `readme.md` file, please supply a main heading with the
+For further details on the yaml file format, and the option types supported by the configurator, see the `jupyter_nbextension_configurator repo <https://github.com/jupyter-contrib/jupyter_nbextensions_configurator>`__.
+
+When supplying a `README.md` file, please supply a main heading with the
 nbextension's title, as this will be linked in the generated documentation at
 `jupyter-contrib-nbextensions.readthedocs.io <http://jupyter-contrib-nbextensions.readthedocs.io/en/latest>`__.
-This is a simple example for `readme.md`::
+This is a simple example for a `README.md`:
+
+.. code-block:: markdown
 
     This extension
     ==============
 
-    How to use
-    ----------
-    Some description here.
+    A quick summary of what this nbextension does.
+
+
+    Usage
+    -----
+
+    A more detailed description can go here, maybe covering different variations of functionality, differences in versions or for different kernels etc.
 
     ![Screenshot image](screenshot.png)
 
+
+    Options
+    -------
+
+    Some description of the different options the nbextension provides, what they do, and their default values
+
     Internals
     ---------
+
     How this extension works.