Contributing to the editor extensions¶
The various editor extensions have different structures and packaging requirements. Where applicable, instructions for contributing can be found in each project’s README. Specifics for packaging and distribution can be found here.
The JupyterLab extension is distributed in two places; via pip and npm. New versions should be published at both locations. You need to have nodejs installed to work with the extension.
First, make sure you have an account on https://pypi.org. An existing collaborator can then invite you to be a maintainer, by going to the project’s collaboration page and entering your username.
To publish an update, run the following from the repository:
$ pip wheel . -w dist
This will create a folder named
dist and build a wheel of the extension there. You
can then publish this to PyPI with twine:
$ twine upload dist/katscript_jupyterlab-*.whl
After following the prompt to login, your update will be published.
npm package is published under the gwoptics organisation. An existing collaborator can invite you to join
the organisation from the members page, either by email or username. Either
way, you’ll need to create an account on https://www.npmjs.com.
To publish an update, you’ll first need to log in to
npm from the command-line:
$ npm login
Next, from the repository, run:
$ npm run build $ npm publish
Your update should then be immediately available from the JupyterLab extension manager.
Files published to https://npmjs.com are permanent; you cannot unpublish a package more than 24 hours after it was published, so take care.
Visual Studio Code¶
The Visual Studio Code extension is published in two places: the Visual Studio Marketplace, which is used by Visual Studio Code, and the open-source Open VSX, which is used by VSCodium and other editors. New versions should be published at both locations. To publish at either location, you’ll need to have nodejs installed. The initial set-up for both locations is fairly involved.
Visual Studio Marketplace¶
The Visual Studio Marketplace extension is published under the gwoptics publisher, which is tied to the corresponding gwoptics Azure DevOps organisation. First, an existing member must invite you to the Azure organisation from the organisation settings page. You then need to obtain a Personal Access Token, as described in the extension guide.
Next, you need to be invited to the gwoptics publisher, which an existing member can do from the publisher management page. An “Invalid Domain” error may occur when adding a new user, in which case the existing member will have to contact Microsoft support from the “Contact Microsoft” link in the top-right. They will need the ID of the new user, which can be obtained as described in this stackoverflow answer, so you may as well send that as part of the request for help.
To actually publish an update, follow the steps in the extension guide. You’ll need your Personal Access Token to log in. These basically amount to running the following from the repository:
$ npx vsce login gwoptics $ npx vsce publish
The Open VSX extension is again under the gwoptics namespace. The following steps are the same as those in the publishing guide.
First, create a GitHub account if you don’t have one. Next, create an Eclipse account, filling in the GitHub Username field with the correct name. You can then log in via https://open-vsx.org/ using this GitHub account. From your profile page, click Log in with Eclipse to authorize Eclipse to access your account. Next, click the newly-added Show Publisher Agreement button on your profile page, and click Agree if you do. An existing member can then add your username to the namespace from their namespaces settings page.
Once you have an account, you’ll have to generate an Access Token from your settings
page. You can then publish the extension
by running the following from the repository, replacing
<token> with your Access
$ npx ovsx publish -p <token>
The Vim extension can be installed in the usual ways, such as with vim-plug or Vim’s built-in package management. No packaging work is required, as it’s installed straight from the git repository.
The Pygments extension is installed along with Finesse by defining the
pygments.lexers entry point in setup.py, so no further
packaging work needs to be done. The actual extension is defined in
script/highlighter.py, and is described there.