document custom.js

IPython/frontend/html/notebook/static/js/custom.js

@@ -1,7 +1,32 @@
-/*
-Placeholder for custom user javascript
-
-mainly to be overridden in profile/static/js/custom.js
-
-This will always be an empty file in IPython
-*/
+// leave at least 2 line with only a star on it below, or doc generation fails
+/**
+ *
+ *
+ * Placeholder for custom user javascript
+ * mainly to be overridden in profile/static/js/custom.js
+ * This will always be an empty file in IPython
+ *
+ * User could add any javascript in the `profile/static/js/custom.js` file
+ * (and should create it if it does not exist).
+ * It will be executed by the ipython notebook at load time.
+ *
+ * Example
+ * Create a custom button in toolbar that execute `%qtconsole` in kernel
+ * and hence open a qtconsole attached to the same kernel as the current notebook
+ *
+ *    $([IPython.events]).on('notebook_loaded.Notebook', function(){
+ *        IPython.toolbar.add_buttons_group([
+ *            {
+ *                 'label'   : 'run qtconsole',
+ *                 'icon'    : 'ui-icon-calculator', // select your icon from http://jqueryui.com/themeroller/
+ *                 'callback': function(){IPython.notebook.kernel.execute('%qtconsole')}
+ *            }
+ *            // add more button here if needed.
+ *            ]);
+ *    });
+ *
+ * @module IPython
+ * @namespace IPython
+ * @class customjs
+ * @static
+ */