Merge pull request #1200 from jcb91/docs

docs updates

Author: jcb91

CHANGELOG.md

@@ -5,10 +5,10 @@ All notable changes to this project should be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres (at least as of 0.3.0!) to
-[Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Note also that since this markdown is used to produce our docs at
-[jupyter-contrib-nbextensions.readthedocs.io](http://jupyter-contrib-nbextensions.readthedocs.io/en/latest/)
+[jupyter-contrib-nbextensions.readthedocs.io](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/)
 via [recommonmark](https://github.com/rtfd/recommonmark), (and GitHub links
 aren't automatically added by recommonmark), it'd be helpful if you could
 explicitly link github PR/issue numbers and any URIs, to make sure our
@@ -760,7 +760,7 @@ New nbextensions, new features and bugfixes:
 Updates to readme/docs:
 
   - get docs readable at
-    [jupyter-contrib-nbextensions.readthedocs.io](http://jupyter-contrib-nbextensions.readthedocs.io/)
+    [jupyter-contrib-nbextensions.readthedocs.io](https://jupyter-contrib-nbextensions.readthedocs.io/)
   - add an auto-enabled nbextension `contrib_nbextensions_help_item`, which
     adds a help menu item to point at RTD
   - Add missing readmes & yaml links to readmes

README.md

@@ -2,8 +2,8 @@ Jupyter notebook extensions
 ===========================
 
 [![Join the chat at https://gitter.im/ipython-contrib/jupyter_contrib_nbextensions](https://img.shields.io/gitter/room/ipython-contrib/jupyter_contrib_nbextensions.svg?maxAge=3600)](https://gitter.im/ipython-contrib/jupyter_contrib_nbextensions?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![Documentation Status](https://readthedocs.org/projects/jupyter-contrib-nbextensions/badge/?version=latest)](http://jupyter-contrib-nbextensions.readthedocs.io/en/latest/)
-[![Documentation Status](https://readthedocs.org/projects/jupyter-contrib-nbextensions/badge/?version=stable)](http://jupyter-contrib-nbextensions.readthedocs.io/en/stable/)
+[![Documentation Status](https://readthedocs.org/projects/jupyter-contrib-nbextensions/badge/?version=latest)](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/)
+[![Documentation Status](https://readthedocs.org/projects/jupyter-contrib-nbextensions/badge/?version=stable)](https://jupyter-contrib-nbextensions.readthedocs.io/en/stable/)
 [![GitHub issues](https://img.shields.io/github/issues/ipython-contrib/jupyter_contrib_nbextensions.svg?maxAge=3600)](https://github.com/ipython-contrib/jupyter_contrib_nbextensions/issues)
 <br/>
 [![Travis-CI Build Status](https://img.shields.io/travis/ipython-contrib/jupyter_contrib_nbextensions.svg?maxAge=3600&label=Travis)](https://travis-ci.org/ipython-contrib/jupyter_contrib_nbextensions)
@@ -47,7 +47,7 @@ Documentation
 =============
 
 Documentation for all maintained extensions can be found at
-[jupyter-contrib-nbextensions.readthedocs.io](http://jupyter-contrib-nbextensions.readthedocs.io/en/latest)
+[jupyter-contrib-nbextensions.readthedocs.io](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest)
 
 In the 4.x Jupyter repository, all extensions that are maintained and active
 have at least a  yaml file to allow them being configured using the
@@ -221,24 +221,27 @@ which will
 
 For complex or customized installation scenarios, please look at the
 documentation for installing notebook extensions, server extensions, nbconvert
-pre/postprocessors and templates on the [Jupyter homepage](http://jupyter.org).
+pre/postprocessors and templates on the [Jupyter homepage](https://jupyter.org).
 More information can also be found in the
 [Wiki](https://github.com/ipython-contrib/jupyter_contrib_nbextensions/wiki).
 
-See also [installing Jupyter](http://jupyter.readthedocs.io/en/latest/install.html)
+See also [installing Jupyter](https://jupyter.readthedocs.io/en/latest/install.html)
 
 
 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/install.md

@@ -153,8 +153,8 @@ which will
 
 For complex or customized installation scenarios, please look at the
 documentation for installing notebook extensions, server extensions, nbconvert
-pre/postprocessors and templates on the [Jupyter homepage](http://jupyter.org).
+pre/postprocessors and templates on the [Jupyter homepage](https://jupyter.org).
 More information can also be found in the
 [Wiki](https://github.com/ipython-contrib/jupyter_contrib_nbextensions/wiki).
 
-See also [installing Jupyter](http://jupyter.readthedocs.io/en/latest/install.html)
+See also [installing Jupyter](https://jupyter.readthedocs.io/en/latest/install.html)

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.
 

docs/source/troubleshooting.md

@@ -45,7 +45,7 @@ Generating Local Documentation
 ------------------------------
 
 The documentation can be found online at readthedocs: 
-    <http://jupyter-contrib-nbextensions.readthedocs.io/en/stable/>
+    <https://jupyter-contrib-nbextensions.readthedocs.io/en/stable/>
 
 If you want to create documentation locally, use
 

src/jupyter_contrib_nbextensions/nbextensions/code_prettify/README.md

@@ -41,7 +41,7 @@ the options are as follows:
 
 - `mod_name.button_icon`:
   A font-awesome class defining the icon used for the toolbar button and
-  actions. See [http://fontawesome.io/icons] for available icon classes.
+  actions. See [fontawesome.io/icons] for available icon classes.
   Defaults to `fa-legal`.
 
 - `mod_name.button_label`:
@@ -276,7 +276,7 @@ History
 [autopep8]: https://github.com/hhatto/autopep8
 [code-prettify]: README_code_prettify.md
 [jupyter-autopep8]: README_autopep8.md
-[http://fontawesome.io/icons]: http://fontawesome.io/icons
+[fontawesome.io/icons]: https://fontawesome.io/icons
 [internals]: #Internals
 [jupyter-autopep8]: https://github.com/kenkoooo/jupyter-autopep8
 [jupyter_nbextensions_configurator]: https://github.com/Jupyter-contrib/jupyter_nbextensions_configurator

src/jupyter_contrib_nbextensions/nbextensions/code_prettify/README_2to3.md

@@ -40,7 +40,7 @@ The options are as follows:
 
 - `2to3.button_icon`:
   A font-awesome class defining the icon used for the toolbar button and
-  actions. See [http://fontawesome.io/icons] for available icon classes.
+  actions. See [fontawesome.io/icons] for available icon classes.
   Defaults to `fa-legal`.
 
 - `2to3.button_label`:
@@ -127,7 +127,7 @@ ways.
 [@takluyver]: https://github.com/takluyver
 [code_prettify]: https://github.com/jfbercher/code_prettify
 [futurize]: http://python-future.org/automatic_conversion.html
-[http://fontawesome.io/icons]: http://fontawesome.io/icons
+[fontawesome.io/icons]: https://fontawesome.io/icons
 [internals]: #Internals
 [jupyter_nbextensions_configurator]: https://github.com/Jupyter-contrib/jupyter_nbextensions_configurator
 [KerneExecOnCells library]: README.md

src/jupyter_contrib_nbextensions/nbextensions/code_prettify/README_autopep8.md

@@ -46,7 +46,7 @@ The options are as follows:
 
 - `autopep8.button_icon`:
   A font-awesome class defining the icon used for the toolbar button and
-  actions. See [http://fontawesome.io/icons] for available icon classes.
+  actions. See [fontawesome.io/icons] for available icon classes.
   Defaults to `fa-cog`.
 
 - `autopep8.button_label`:
@@ -125,7 +125,7 @@ calls to the active kernel.
 [@kenkoooo]: https://github.com/kenkoooo
 [autopep8]: https://github.com/hhatto/autopep8
 [code_prettify]: https://github.com/jfbercher/code_prettify
-[http://fontawesome.io/icons]: http://fontawesome.io/icons
+[fontawesome.io/icons]: https://fontawesome.io/icons
 [internals]: #Internals
 [jupyter_nbextensions_configurator]: https://github.com/Jupyter-contrib/jupyter_nbextensions_configurator
 [KerneExecOnCells library]: README.md

src/jupyter_contrib_nbextensions/nbextensions/code_prettify/README_code_prettify.md

@@ -95,7 +95,7 @@ The options are as follows:
 
 - `code_prettify.button_icon`:
   A font-awesome class defining the icon used for the toolbar button and
-  actions. See [http://fontawesome.io/icons] for available icon classes.
+  actions. See [fontawesome.io/icons] for available icon classes.
   Defaults to `fa-legal`.
 
 - `code_prettify.button_label`:
@@ -281,8 +281,8 @@ History
 [@jfbercher]: https://github.com/jfbercher
 [autopep8]: https://github.com/hhatto/autopep8
 [formatR]: https://yihui.name/formatr
-[http://fontawesome.io/icons]: http://fontawesome.io/icons
-[ijavascript]: http://n-riesco.github.io/ijavascript
+[fontawesome.io/icons]: https://fontawesome.io/icons
+[ijavascript]: https://n-riesco.github.io/ijavascript
 [internals]: #Internals
 [js-beautify]: https://github.com/beautify-web/js-beautify
 [jsonlite]: https://github.com/jeroenooms/jsonlite
@@ -292,5 +292,5 @@ History
 [options]: #Options
 [prerequisites]: #Prerequisites
 [README_autopep8.md]: README_autopep8.md
-[this question on stackoverflow]: http://stackoverflow.com/questions/9587665/nodejs-cannot-find-installed-module-on-windows
+[this question on stackoverflow]: https://stackoverflow.com/questions/9587665/nodejs-cannot-find-installed-module-on-windows
 [yapf]: https://github.com/google/yapf

src/jupyter_contrib_nbextensions/nbextensions/execute_time/readme.md

@@ -129,7 +129,7 @@ and
 [jupyter/jupyter_client#143](https://github.com/jupyter/jupyter_client/issues/143),
 although they are (now) supposed to, Jupyter kernels don't always specify a
 timezone for their timestamps, which can cause problems when the
-[moment.js](http://momentjs.com/)
+[moment.js](https://momentjs.com/)
 library assumes the local timezone, rather than UTC, which is what most kernels
 are actually using.
 To help to address this, see the [options](#Options) above, which can be used
@@ -179,14 +179,14 @@ strings, for example:
 ```
 
 The times in the timing areas are formatted using the
-[moment.js](http://momentjs.com/) library (already included as part of
+[moment.js](https://momentjs.com/) library (already included as part of
 Jupyter), but the durations use a custom formatting function, as
 I ([@jcb91](https://github.com/jcb91))
 couldn't find an existing one that I liked.
 
 The event `execute.CodeCell` is caught in order to create a start time, and add
 the timing area with its 'Execution queued at' message.
-The extension again uses [moment.js](http://momentjs.com/) for formatting this
+The extension again uses [moment.js](https://momentjs.com/) for formatting this
 as an ISO string time.
 
 To determine the execution time, the extension patches the Jupyter class
@@ -202,5 +202,5 @@ the `msg.metadata.started` value supplied in the callback, which can be very
 different from the time the cell was queued for execution (as a result of
 other cells already being executed).
 The kernel reply message times are already ISO8601 strings, so no conversion is
-necessary, although again, [moment.js](http://momentjs.com/) is used for
+necessary, although again, [moment.js](https://momentjs.com/) is used for
 parsing and diff'ing them.