Name: mimerender-cookiecutter
Owner: JupyterLab
Description: A cookiecutter for rendering MIME type based output
Created: 2016-10-24 21:47:08.0
Updated: 2018-01-09 22:22:43.0
Pushed: 2017-11-20 17:45:01.0
Homepage: null
Size: 170
Language: Python
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
A cookiecutter template for creating a JupyterLab and Jupyter Notebook extension for rendering specific mime types and file extensions.
Install cookiecutter:
install cookiecutter
Use cookiecutter to generate a package:
iecutter https://github.com/jupyterlab/mimerender-cookiecutter
The cookiecutter will prompt you with the following questions and generate a project according to your responses:
author_name
: Your full name. This will be used in the generated Python and npm packages.author_email
: Your email address. This will be used in the generated Python and npm packages.mime_type
: A valid mime type (e.g. application/json
, application/geo+json
). This will be used to render output data of this mime type with your extension.mime_short_name
: A display name (no spaces) for your mime type (e.g. JSON
, GeoJSON
). This will be used in the generated Python and npm packages, README, and class names.file_type
: OPTIONAL A valid file type (e.g. json
, geojson
). This will be used to open files of this type with your extension.extension_name
: Your JupyterLab and Jupyter Notebook extension name (e.g. jupyerlab_json
, jupyerlab_geojson
).The project is divided into 2 top-level directories, one for each extension (lab and notebook).
In most cases, you will only need to edit the OutputWidget._render
method in labextension/src/output.js
(for rendering output data of a specific mime type) and the DocWidget.onUpdateRequest
method in labextension/src/doc.js
(if your extension should render files of a specific type).
extension_name
extension_name
: The Python packagestatic
: Compiled Javascript for the notebook extension.__init__.py
: Exports paths and metadata of lab and notebook extensions and exports an optional display
method that can be imported into a notebook and used to easily display data using this renderersrc
- The extension source.embed.js
: Entry point for embedded widgetextension.js
: Integration point with Jupyter Notebookindex.js
: Entry point for the Jupyter Notebook extensionplugin.js
: Entry point for the JupyterLab extensionrenderer.js
: Methods for rendering output data of mime_type
defined in promptsThis cookiecutter will change over time to adapt to API changes and best practices, so you should be able to rebase your extension from an updated version of the cookiecutter. The following is the recommended workflow:
cookiecutter
that will serve as the base for another branch called develop
. All feature branches shoud be based on develop
and merged into master
.cookiecutter
branch: git checkout cookiecutter
cookiecutter https://github.com/jupyterlab/mimerender-cookiecutter [--checkout BRANCH_NAME] --output-dir .. --config-file .cookiecutter.yaml --no-input --overwrite-if-exists
--checkout
is optional and specifies a branch of mimerender-cookiecutter to checkout (e.g. react
).--output-dir ..
allows us to run the cookiecutter in the repo root vs. the parent directory because cookiecutter will always render output in a child directory of the output-dir
.--config-file .cookiecutter.yaml
will run the cookiecutter with the original inputs which are persisted to .cookiecutter.yaml
in the repo root.--no-input
will skip the cookiecutter prompts.--overwrite-if-exists
will replace our previous cookiecutter output with the most up-to-date output.cookiecutter
with a message like “mimerender-cookiecutter [VERSION_NUMBER]“: git commit -m "mimerender-cookiecutter [VERSION_NUMBER]"
develop
branch: git checkout develop
cookiecutter
: git rebase cookiecutter
git rebase --continue
RELEASE.md
.We suggest that extension names start with jupyterlab_
and use underscores if needed to improve readability, such as jupyterlab_myextension
.