Merge pull request #42 from jasongrout/updates

jasongrout · web-flow · commit 51e9fed8687e · 2018-12-26T12:29:50.000-08:00
More updates
diff --git a/README.md b/README.md
@@ -34,8 +34,6 @@ information:
 - `npm_package_name`: name for the npm "front-end" package holding the JavaScript
   implementation used in your custom widget.
 - `npm_package_version`: initial version of the npm package.
-- `jlab_extension_id`: extension ID to supply to JupyterLab when registering the extension.
-  The recommended format is "jupyter.extensions.<Your UNIQUE designator here>".
 - `project_short_description` : a short description for your project that will
   be used for both the "back-end" and "front-end" packages.
 
@@ -64,7 +62,7 @@ jupyter labextension install .
 For classic notebook, you can run:
 
 ```
-jupyter nbextension install --sys-prefix --symlink --py <your python package name>
+jupyter nbextension install --sys-prefix --symlink --overwrite --py <your python package name>
 jupyter nbextension enable --sys-prefix --py <your python package name>
 ```
 
diff --git a/cookiecutter.json b/cookiecutter.json
@@ -1,11 +1,10 @@
 {
 	"author_name": "",
 	"author_email": "",
-	"github_project_name": "jupyter-widget-example",
-	"github_organization_name": "jupyter",
-	"python_package_name": "ipywidgetexample",
-	"npm_package_name": "jupyter-widget-example",
+	"github_project_name": "",
+	"github_organization_name": "",
+	"python_package_name": "{{ cookiecutter.github_project_name }}",
+	"npm_package_name": "{{ cookiecutter.github_project_name }}",
     "npm_package_version": "0.1.0",
-    "jlab_extension_id": "jupyter.extensions.example",
 	"project_short_description": "A Custom Jupyter Widget Library"
 }
diff --git a/tests/testconfig.yaml b/tests/testconfig.yaml
@@ -4,7 +4,6 @@ default_context:
     github_project_name: "jupyter-widget-testwidgets"
     github_organization_name: "jupyter"
     python_package_name: "ipywidgettestwidgets"
-    npm_package_name: "jupyter-widget-testwidgets"
+    npm_package_name: "@jupyter-widgets/jupyter-widget-testwidgets"
     npm_package_version: "1.1.0"
-    jlab_extension_id: "jupyter.extensions.testwidgets"
     project_short_description: "A Test Jupyter Widget Library"
diff --git a/{{cookiecutter.github_project_name}}/LICENSE.txt b/{{cookiecutter.github_project_name}}/LICENSE.txt
@@ -1,21 +1,19 @@
-BSD 3-Clause License
-
-Copyright (c) {% now 'local', '%Y' %}, {{ cookiecutter.author_name }}
+Copyright (c) {% now 'local', '%Y' %} {{ cookiecutter.author_name }}
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
 
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
 
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
 
-* Neither the name of the copyright holder nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
diff --git a/{{cookiecutter.github_project_name}}/README.md b/{{cookiecutter.github_project_name}}/README.md
@@ -9,16 +9,21 @@
 
 ## Installation
 
-A typical installation requires the following commands to be run:
+You can install using `pip`:
 
 ```bash
 pip install {{ cookiecutter.python_package_name  }}
-jupyter nbextension enable --py [--sys-prefix|--user|--system] {{ cookiecutter.python_package_name  }}
 ```
 
-Or, if you use jupyterlab:
+Or if you use jupyterlab:
 
 ```bash
 pip install {{ cookiecutter.python_package_name  }}
 jupyter labextension install @jupyter-widgets/jupyterlab-manager
 ```
+
+If you are using Jupyter Notebook 5.2 or earlier, you may also need to enable
+the nbextension:
+```bash
+jupyter nbextension enable --py [--sys-prefix|--user|--system] {{ cookiecutter.python_package_name  }}
+```
diff --git a/{{cookiecutter.github_project_name}}/package.json b/{{cookiecutter.github_project_name}}/package.json
@@ -17,7 +17,10 @@
     "url": "https://github.com/{{ cookiecutter.github_organization_name }}/{{ cookiecutter.github_project_name }}/issues"
   },
   "license": "BSD-3-Clause",
-  "author": "",
+  "author": {
+    "name": "{{ cookiecutter.author_name }}",
+    "email": "{{ cookiecutter.author_email }}"
+  },
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
   "repository": {
@@ -27,7 +30,7 @@
   "scripts": {
     "build": "npm run build:lib && npm run build:nbextension",
     "build:labextension": "npm run clean:labextension && mkdirp {{ cookiecutter.python_package_name }}/labextension && cd {{ cookiecutter.python_package_name }}/labextension && npm pack ../..",
-    "build:lib": "tsc --project src",
+    "build:lib": "tsc",
     "build:nbextension": "webpack -p",
     "build:all": "npm run build:labextension && npm run build:nbextension",
     "clean": "npm run clean:lib && npm run clean:nbextension",
@@ -41,7 +44,7 @@
     "test:firefox": "karma start --browsers=Firefox tests/karma.conf.js",
     "test:ie": "karma start --browsers=IE tests/karma.conf.js",
     "watch": "npm-run-all -p watch:*",
-    "watch:lib": "tsc -w --project src",
+    "watch:lib": "tsc -w",
     "watch:nbextension": "webpack --watch"
   },
   "dependencies": {
diff --git a/{{cookiecutter.github_project_name}}/setup.py b/{{cookiecutter.github_project_name}}/setup.py
@@ -44,10 +44,10 @@
 }
 
 data_files_spec = [
-    ('share/jupyter/nbextensions/{{ cookiecutter.npm_package_name }}',
+    ('share/jupyter/nbextensions/{{ cookiecutter.python_package_name}}',
         nb_path, '*.js*'),
     ('share/jupyter/lab/extensions', lab_path, '*.tgz'),
-    ('etc/jupyter/nbconfig/notebook.d' , HERE, '{{ cookiecutter.npm_package_name }}.json')
+    ('etc/jupyter/nbconfig/notebook.d' , HERE, '{{ cookiecutter.python_package_name}}.json')
 ]
 
 
@@ -101,7 +101,7 @@
             'sphinx>=1.5',
             'recommonmark',
             'sphinx_rtd_theme',
-            'nbsphinx>=0.2.13',
+            'nbsphinx>=0.2.13,<0.4.0',
             'jupyter_sphinx',
             'nbsphinx-link',
             'pytest_check_links',
diff --git a/{{cookiecutter.github_project_name}}/src/extension.ts b/{{cookiecutter.github_project_name}}/src/extension.ts
@@ -8,6 +8,6 @@
 // Some static assets may be required by the custom widget javascript. The base
 // url for the notebook is not known at build time and is therefore computed
 // dynamically.
-__webpack_public_path__ = document.querySelector('body')!.getAttribute('data-base-url') + 'nbextensions/{{ cookiecutter.npm_package_name }}';
+(window as any).__webpack_public_path__ = document.querySelector('body')!.getAttribute('data-base-url') + 'nbextensions/{{ cookiecutter.npm_package_name }}';
 
 export * from './index';
diff --git a/{{cookiecutter.github_project_name}}/src/index.ts b/{{cookiecutter.github_project_name}}/src/index.ts
@@ -1,4 +1,5 @@
+// Copyright (c) {{ cookiecutter.author_name }}
+// Distributed under the terms of the Modified BSD License.
 
-export * from './plugin';
 export * from './version';
 export * from './widget';
diff --git a/{{cookiecutter.github_project_name}}/src/plugin.ts b/{{cookiecutter.github_project_name}}/src/plugin.ts
@@ -1,4 +1,4 @@
-// Copyright (c) Jupyter Development Team.
+// Copyright (c) {{ cookiecutter.author_name }}
 // Distributed under the terms of the Modified BSD License.
 
 import {
@@ -19,8 +19,7 @@ import {
   MODULE_NAME, MODULE_VERSION
 } from './version';
 
-const EXTENSION_ID = '{{ cookiecutter.jlab_extension_id }}';
-
+const EXTENSION_ID = '{{ cookiecutter.npm_package_name }}:plugin';
 
 /**
  * The example plugin.
diff --git a/{{cookiecutter.github_project_name}}/src/version.ts b/{{cookiecutter.github_project_name}}/src/version.ts
@@ -1,10 +1,13 @@
-// Copyright (c) {{ cookiecutter.author_name }}.
+// Copyright (c) {{ cookiecutter.author_name }}
 // Distributed under the terms of the Modified BSD License.
 
 const data = require('../package.json');
 
 /**
- * The current package version.
+ * The _model_module_version/_view_module_version this package implements.
+ *
+ * The html widget manager assumes that this is the same as the npm package
+ * version number.
  */
 export const MODULE_VERSION = data.version;
 
diff --git a/{{cookiecutter.github_project_name}}/src/widget.ts b/{{cookiecutter.github_project_name}}/src/widget.ts
@@ -1,4 +1,4 @@
-// Copyright (c) {{ cookiecutter.author_name }}.
+// Copyright (c) {{ cookiecutter.author_name }}
 // Distributed under the terms of the Modified BSD License.
 
 import {
diff --git a/{{cookiecutter.github_project_name}}/tests/karma.conf.js b/{{cookiecutter.github_project_name}}/tests/karma.conf.js
@@ -27,7 +27,7 @@ module.exports = function (config) {
 
 
     karmaTypescriptConfig: {
-      tsconfig: 'tests/src/tsconfig.json',
+      tsconfig: 'tests/tsconfig.json',
       reports: {
         "text-summary": "",
         "html": "coverage",
diff --git a/{{cookiecutter.github_project_name}}/tests/tsconfig.json b/{{cookiecutter.github_project_name}}/tests/tsconfig.json
@@ -8,11 +8,12 @@
     "module": "commonjs",
     "moduleResolution": "node",
     "target": "ES5",
-    "outDir": "../build",
+    "outDir": "build",
     "skipLibCheck": true,
     "sourceMap": true
   },
   "include": [
-    "**/*.ts"
+    "src/*.ts",
+    "../src/**/*.ts"
   ]
 }
diff --git a/{{cookiecutter.github_project_name}}/tsconfig.json b/{{cookiecutter.github_project_name}}/tsconfig.json
@@ -7,10 +7,14 @@
     "moduleResolution": "node",
     "noEmitOnError": true,
     "noUnusedLocals": true,
-    "outDir": "../lib",
+    "outDir": "lib",
+    "resolveJsonModule": true,
+    "rootDir": "src",
     "skipLibCheck": true,
     "sourceMap": true,
     "strict": true,
-    "target": "es2015"
-  }
+    "target": "es2015",
+    "types": ["node"]
+  },
+  "include": ["src/*"]
 }
diff --git a/{{cookiecutter.github_project_name}}/webpack.config.js b/{{cookiecutter.github_project_name}}/webpack.config.js
@@ -1,21 +1,29 @@
+const path = require('path');
+const version = require('./package.json').version;
+
 // Custom webpack rules
 const rules = [
   { test: /\.ts$/, loader: 'ts-loader' },
   { test: /\.js$/, loader: 'source-map-loader' },
+  { test: /\.css$/, use: ['style-loader', 'css-loader']}
 ];
 
-const version = require('./package.json').version;
-const path = require('path');
-
+// Packages that shouldn't be bundled but loaded at runtime
+const externals = ['@jupyter-widgets/base'];
 
 const resolve = {
   // Add '.ts' and '.tsx' as resolvable extensions.
   extensions: [".webpack.js", ".web.js", ".ts", ".js"]
 };
 
 module.exports = [
+  /**
+   * Notebook extension
+   *
+   * This bundle only contains the part of the JavaScript that is run on load of
+   * the notebook.
+   */
   {
-    // Notebook extension
     entry: './src/extension.ts',
     output: {
       filename: 'index.js',
@@ -26,40 +34,21 @@ module.exports = [
       rules: rules
     },
     devtool: 'source-map',
-    externals: ['@jupyter-widgets/base'],
+    externals,
     resolve,
   },
 
+  /**
+   * Embeddable {{ cookiecutter.npm_package_name }} bundle
+   *
+   * This bundle is almost identical to the notebook extension bundle. The only
+   * difference is in the configuration of the webpack public path for the
+   * static assets.
+   *
+   * The target bundle is always `dist/index.js`, which is the path required by
+   * the custom widget embedder.
+   */
   {
-    // embeddable bundle (e.g. for docs)
-    entry: './src/index.ts',
-    output: {
-      filename: 'embed-bundle.js',
-      path: path.resolve(__dirname, 'docs', 'source', '_static'),
-      library: "{{ cookiecutter.npm_package_name }}",
-      libraryTarget: 'amd'
-    },
-    module: {
-      rules: rules
-    },
-    devtool: 'source-map',
-    externals: ['@jupyter-widgets/base'],
-    resolve,
-  },
-  {// Embeddable {{ cookiecutter.npm_package_name }} bundle
-    //
-    // This bundle is generally almost identical to the notebook bundle
-    // containing the custom widget views and models.
-    //
-    // The only difference is in the configuration of the webpack public path
-    // for the static assets.
-    //
-    // It will be automatically distributed by unpkg to work with the static
-    // widget embedder.
-    //
-    // The target bundle is always `dist/index.js`, which is the path required
-    // by the custom widget embedder.
-    //
     entry: './src/index.ts',
     output: {
         filename: 'index.js',
@@ -72,7 +61,30 @@ module.exports = [
     module: {
         rules: rules
     },
-    externals: ['@jupyter-widgets/base'],
+    externals,
+    resolve,
+  },
+
+
+  /**
+   * Documentation widget bundle
+   *
+   * This bundle is used to embed widgets in the package documentation.
+   */
+  {
+    entry: './src/index.ts',
+    output: {
+      filename: 'embed-bundle.js',
+      path: path.resolve(__dirname, 'docs', 'source', '_static'),
+      library: "{{ cookiecutter.npm_package_name }}",
+      libraryTarget: 'amd'
+    },
+    module: {
+      rules: rules
+    },
+    devtool: 'source-map',
+    externals,
     resolve,
   }
+
 ];
diff --git a/{{cookiecutter.github_project_name}}/{{cookiecutter.npm_package_name}}.json b/{{cookiecutter.github_project_name}}/{{cookiecutter.npm_package_name}}.json
diff --git a/{{cookiecutter.github_project_name}}/{{cookiecutter.python_package_name}}.json b/{{cookiecutter.github_project_name}}/{{cookiecutter.python_package_name}}.json
@@ -0,0 +1,5 @@
+{
+  "load_extensions": {
+    "{{ cookiecutter.python_package_name}}/extension": true
+  }
+}
diff --git a/{{cookiecutter.github_project_name}}/{{cookiecutter.python_package_name}}/nbextension/__init__.py b/{{cookiecutter.github_project_name}}/{{cookiecutter.python_package_name}}/nbextension/__init__.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # coding: utf-8
 
-# Copyright (c) {{ cookiecutter.author_name }}.
+# Copyright (c) {{ cookiecutter.author_name }}
 # Distributed under the terms of the Modified BSD License.
 
 def _jupyter_nbextension_paths():
diff --git a/{{cookiecutter.github_project_name}}/{{cookiecutter.python_package_name}}/nbextension/static/extension.js b/{{cookiecutter.github_project_name}}/{{cookiecutter.python_package_name}}/nbextension/static/extension.js
@@ -1,3 +1,5 @@
+// Entry point for the notebook bundle containing custom model definitions.
+//
 define(function() {
     "use strict";
 
@@ -8,7 +10,7 @@ define(function() {
             },
         }
     });
-    // Export the required load_ipython_extention
+    // Export the required load_ipython_extension function
     return {
         load_ipython_extension : function() {}
     };
