Simplify and document better #6
Conversation
|
|
||
| ``` | ||
| cookiecutter https://github.com/jupyter/jupyterlab-extension-cookiecutter | ||
| ``` | ||
|
|
||
| A very simple working extension, written in common JavaScript, is included in | ||
| the ``lib/`` directory. Use this example to build your own extension. | ||
| A very simple working extension, written in Javascript using CommonJS modules, is included in the ``lib/`` directory. Use this example to build your own extension. |
There was a problem hiding this comment.
Let's flip line 19 and 21.
Add a heading:
A simple example
The lib/ directory includes a very simple example of a working extension, written in JavaScript using CommonJS modules. Use this example as a guide to build your own extension.
|
|
||
| ## Package names | ||
|
|
||
| JupyterLab extensions generated by this cookie cutter recipe are composed of both a python package and an npm package. The npm package is declared as a private package, so it cannot be published to the public npm package repository. The npm package is used to retrieve npm dependencies and provide a framework for the bundling of the javascript. The python package is published to the PyPI python package repository, and contains the generated JupyterLab extension Javascript bundle. |
There was a problem hiding this comment.
This cookiecutter template creates a JupyterLab extension composed of a Python package and an npm package:
- The npm package is declared as a private package, so it cannot be published to the public npm package repository. The npm package is used to retrieve npm dependencies and provide a framework for the bundling of the JavaScript.
- The Python package is published to PyPI, the Python package repository, and contains the generated JupyterLab extension JavaScript bundle.
Thanks to @willingc for review suggestions.
|
|
||
| JupyterLab extensions generated by this cookie cutter recipe are composed of both a python package and an npm package. The npm package is declared as a private package, so it cannot be published to the public npm package repository. The npm package is used to retrieve npm dependencies and provide a framework for the bundling of the javascript. The python package is published to the PyPI python package repository, and contains the generated JupyterLab extension Javascript bundle. | ||
|
|
||
| To lessen confusion between the different packages, this recipe sets the extension name, the python package name, and the npm package name all to the same thing. We also use the python package name as the python module name. A consequence of this is that the extension name should be a valid python import name (e.g., cannot contain dashes). |
There was a problem hiding this comment.
To simplify the developer experience and lessen confusion between the different packages, the cookiecutter template unifies the extension name, the Python package name, and the npm package name to the same name. Make sure to use a valid Python name (i.e. cannot contain dashes) for the extension name since the extension is used as a Python module as well as a Python package.
|
|
||
| ### Clean the repository | ||
|
|
||
| To ensure a clean build, you can remove all non-tracked files with: |
There was a problem hiding this comment.
... build, remove all non-tracked files using the following command from the repository's root directory:
| git clean -xfdi | ||
| ``` | ||
|
|
||
| This would ask you for confirmation before removing all untracked files. |
| ### Create the release | ||
|
|
||
| We publish a Python source package and a Python universal binary wheel. | ||
| See the Python docs on [package uploading](https://packaging.python.org/distributing/#uploading-your-project-to-pypi) |
|
|
||
| We publish a Python source package and a Python universal binary wheel. | ||
| See the Python docs on [package uploading](https://packaging.python.org/distributing/#uploading-your-project-to-pypi) | ||
| for twine setup instructions and for why twine is the recommended uploading method. |
There was a problem hiding this comment.
Link twine
Use GitHub since there are no docs for twine
|
@jasongrout Looks good. A few comments to make it easier for folks using the template. Simple is better than complex. @danielballan thoughts? |
|
@willingc - thanks! Could you take one more look at https://github.com/jasongrout/jupyterlab-extension-cookiecutter/blob/3d9d28cddf4847f932bfd437c67495a3006b377d/%7B%7Bcookiecutter.extension_name%7D%7D/RELEASE.md? I revised it significantly. |
|
Will review RELEASE.md now 👍 |
| @@ -0,0 +1,38 @@ | |||
| # Making a {{ cookiecutter.extension_name }} release | |||
|
|
|||
| This document guides a contributor through creating a release of {{ cookiecutter.extension_name }}. | |||
There was a problem hiding this comment.
Perhaps instead of contributor this should be "extension maintainer"
| This document guides a contributor through creating a release of {{ cookiecutter.extension_name }}. | ||
|
|
||
|
|
||
| We publish a Python source package and a Python universal binary wheel. |
There was a problem hiding this comment.
This process creates and publishes...
|
|
||
| ## Remove generated files | ||
|
|
||
| Do `npm run clean` to remove any old Javascript builds. Delete the `dist/` folder to remove old python package builds. |
There was a problem hiding this comment.
JavaScript builds, and delete .... Python ... :
|
|
||
| ## Build the package | ||
|
|
||
| First build the Javascript extension bundle, then build the python package and wheel. |
There was a problem hiding this comment.
Using the following, build the JavaScript extension bundle and the Python package and wheel:
|
|
||
| ## Upload the package | ||
|
|
||
| Upload the python package with [twine](https://github.com/pypa/twine). See the Python documentation on [package uploading](https://packaging.python.org/distributing/#uploading-your-project-to-pypi) |
|
@jasongrout I like the changes. A few clarifications and dreaded capitalizations 😨 |
Thanks again to @willingc for suggestions.
|
|
|
Great! I agree that one extension name is a good simplification here. |
I think the purpose of the cookie cutter is to be very opinionated, to set some conventions for packages. Accordingly, I simplified all of the names down to a single
extension_namesetting.I also added some readme files.