Skip to content

Commit

Permalink
add trove classifer docs, usage (#10731)
Browse files Browse the repository at this point in the history 
* add trove classifer docs, usage

* split up canonical list, example, and link

* add prebuilt

* address review comments

* change media types to mime renderers

* spelling

* fix dev trove classifiers code block, add user classifier docs

* fix some rst links, sorting
  • Loading branch information
@bollwyvl
bollwyvl committed Aug 10, 2021
1 parent aef7e9e commit 7fee5a2
Show file tree
Hide file tree
Showing 3 changed files with 107 additions and 21 deletions.
51 changes: 50 additions & 1 deletion docs/source/extension/extension_dev.rst
View file
Expand Up @@ -172,7 +172,7 @@ document can then be saved by the user in the usual manner.
Theme plugins
^^^^^^^^^^^^^

A theme is a special application plugin that registers a theme with the ``ThemeManager`` service. Theme CSS assets are specially bundled in an extension (see :ref:`themePath`) so they can be unloaded or loaded as the theme is activated. Since CSS files referenced by the ``style`` or ``styleModule`` keys are automatically bundled and loaded on the page, the theme files should not be referenced by these keys.
A theme is a special application plugin that registers a theme with the ``ThemeManager`` service. Theme CSS assets are specially bundled in an extension (see :ref:`themePath`) so they can be unloaded or loaded as the theme is activated. Since CSS files referenced by the ``style`` or ``styleModule`` keys are automatically bundled and loaded on the page, the theme files should not be referenced by these keys.

The extension package containing the theme plugin must include all static assets that are referenced by ``@import`` in its theme CSS files. Local URLs can be used to reference files relative to the location of the referring sibling CSS files. For example ``url('images/foo.png')`` or ``url('../foo/bar.css')`` can be used to refer local files in the theme. Absolute URLs (starting with a ``/``) or external URLs (e.g. ``https:``) can be used to refer to external assets.

Expand Down Expand Up @@ -570,7 +570,56 @@ This ``install.json`` file is used by JupyterLab to help a user know how to mana
* ``packageName``: This is the package name of the prebuilt extension in the package manager above, which may be different than the package name in ``package.json``.
* ``uninstallInstructions``: This is a short block of text giving the user instructions for uninstalling the prebuilt extension. For example, it might instruct them to use a system package manager or talk to a system administrator.

.. _dev_trove_classifiers:

PyPI Trove Classifiers
""""""""""""""""""""""

Extensions distributed as Python packages may declare additional metadata in the form of
`trove classifiers <https://pypi.org/classifiers>`__. These improve the browsing
experience for users on `PyPI <https://pypi.org/search>`__. While including the license,
development status, Python versions supported, and other topic classifiers are useful
for many audiences, the following classifiers are specific to Jupyter and JupyterLab.

.. code-block::
Framework :: Jupyter
Framework :: Jupyter :: JupyterLab
Framework :: Jupyter :: JupyterLab :: 1
Framework :: Jupyter :: JupyterLab :: 2
Framework :: Jupyter :: JupyterLab :: 3
Framework :: Jupyter :: JupyterLab :: 4
Framework :: Jupyter :: JupyterLab :: Extensions
Framework :: Jupyter :: JupyterLab :: Extensions :: Mime Renderers
Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Framework :: Jupyter :: JupyterLab :: Extensions :: Themes
Include each relevant classifier (and its parents) to help describe what your package
provides to prospective users in your ``setup.py``, ``setup.cfg``, or ``pyproject.toml``.

.. hint::

For example, a theme, only compatible with JupyterLab 3, and distributed as
a ready-to-run, prebuilt extension might look like:

.. code-block:: python
# setup.py
setup(
# the rest of the package's metadata
# ...
classifiers=[
"Framework :: Jupyter",
"Framework :: Jupyter :: JupyterLab",
"Framework :: Jupyter :: JupyterLab :: 3",
"Framework :: Jupyter :: JupyterLab :: Extensions",
"Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt",
"Framework :: Jupyter :: JupyterLab :: Extensions :: Themes",
]
)
This would be discoverable from, for example, a
`PyPI search for theme extensions <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab+%3A%3A+Extensions+%3A%3A+Themes>`__.

.. _source_dev_workflow:

Expand Down
74 changes: 54 additions & 20 deletions docs/source/user/extensions.rst
View file
Expand Up @@ -27,9 +27,45 @@ A JupyterLab extension contains JavaScript that is installed into Jupyterlab and

JupyterLab extensions can be installed in a number of ways, including:

- Python ``pip`` or ``conda`` packages can include either a source extension or a prebuilt extension. These packages may also include a server-side component necessary for the extension to function.
- Python :ref:`pip <user_trove_classifiers>` or ``conda`` packages can include either a source extension or a prebuilt extension. These packages may also include a server-side component necessary for the extension to function.
- The Extension Manager in JupyterLab and the ``jupyter labextension install`` command can install source extension packages from `npm <https://www.npmjs.com/search?q=keywords:jupyterlab-extension>`__. Installing a source extension requires Node.js and a JupyterLab rebuild to activate. See :ref:`installing_nodejs` and :ref:`install_command`.

.. _user_trove_classifiers:

Browsing Extensions on PyPI
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Python Package Index (PyPI) is a repository of software for the Python
programming language, and the default source of packages for the ``pip`` package
manager. While a `simple text search <https://pypi.org/search/?q=jupyterlab&o=>`__
will reveal hundreds of packages, a number of
`trove classifiers <https://pypi.org/classifiers>`__ are available for packages
to self-describe the features and compatibility provided:

- `Framework :: Jupyter :: JupyterLab <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab>`__
- `Framework :: Jupyter :: JupyterLab :: 1 <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab+%3A%3A+1>`__
- `Framework :: Jupyter :: JupyterLab :: 2 <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab+%3A%3A+2>`__
- `Framework :: Jupyter :: JupyterLab :: 3 <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab+%3A%3A+3>`__
- `Framework :: Jupyter :: JupyterLab :: 4 <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab+%3A%3A+4>`__
- `Framework :: Jupyter :: JupyterLab :: Extensions <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab+%3A%3A+Extensions>`__
- `Framework :: Jupyter :: JupyterLab :: Extensions :: Mime Renderers <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab+%3A%3A+Extensions+%3A%3A+Mime+Renderers>`__
- `Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab+%3A%3A+Extensions+%3A%3A+Prebuilt>`__
- `Framework :: Jupyter :: JupyterLab :: Extensions :: Themes <https://pypi.org/search/?c=Framework+%3A%3A+Jupyter+%3A%3A+JupyterLab+%3A%3A+Extensions+%3A%3A+Themes>`__

.. note::

These classifiers were accepted in early August 2021, and it will take some
time for them to be broadly adopted.

*You can help!* The proposal of classifiers to a packages's ``setup.py``,
``setup.cfg``, or ``pyproject.toml`` can make a *great* first open source
:ref:`contribution <dev_trove_classifiers>`, as such contributions are:

- easy for *you*, often possible directly through a project's source code
website, e.g. GitHub or GitLab,
- easy for maintainers to review and merge, and
- can have a positive impact on the discoverability of the package

.. _installing_nodejs:

Installing Node.js
Expand All @@ -42,7 +78,7 @@ JupyterLab and activate the extension. If you use ``conda`` with
.. code:: bash
conda install -c conda-forge nodejs
If you use ``conda`` with default Anaconda packages (i.e., you don't normally
use ``conda-forge``), you should install Node.js from the Anaconda default
channel with ``conda install nodejs`` instead.
Expand All @@ -58,7 +94,7 @@ Managing Extensions with ``jupyter labextension``
-------------------------------------------------

The ``jupyter labextension`` command enables you to install or uninstall
source extensions from `npm <https://www.npmjs.com/search?q=keywords:jupyterlab-extension>`__, list all installed extensions, or disable any extension. See the help with ``jupyter labextension --help``.
source extensions from `npm <https://www.npmjs.com/search?q=keywords:jupyterlab-extension>`__, list all installed extensions, or disable any extension. See the help with ``jupyter labextension --help``.

Installing and Uninstalling Source Extensions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -150,12 +186,12 @@ Extensions or individual plugins within an extension can be disabled by another

The priority order for determining whether an extension is enabled or disabled is as follows:

- Presence of ``<jupyter_config_path>/labconfig/pageconfig.json`` file(s) with a ``disabledExtensions`` key that is a object with package names as keys and boolean values.
- Presence of ``<jupyter_config_path>/labconfig/pageconfig.json`` file(s) with a ``disabledExtensions`` key that is a object with package names as keys and boolean values.
- (deprecated) Presence of ``disabledExtensions`` key in ``<lab_app_dir>/settings/pageconfig.json``. This value is a list of extensions to disable, but is deprecated in favor of the layered configuration approach in the `labconfig` location(s).
- Presence of ``disabledExtensions`` key in another JupyterLab extension's metadata that disables a given extension. The key is ignored if that extension itself is disabled.

When using the command line, you can target the ``--level`` of the config: ``user``, ``system``, or ``sys-prefix`` (default).

An example ``<jupyter_config_path>/labconfig/pageconfig.json`` could look as follows:

.. code:: json
Expand All @@ -178,7 +214,7 @@ The Extension Manager is in the :ref:`left sidebar <left-sidebar>`.

.. figure:: images/extension_manager_default.png
:align: center
:class: jp-screenshotls
:class: jp-screenshotls

**Figure:** The default view has three components: a search bar, an "Installed"
section, and a "Discover" section.
Expand Down Expand Up @@ -214,7 +250,7 @@ but can not install it (no install button is available).


To install an extension, you first have to explicitly acknowledge the disclaimer.
Once done, this will remain across sessions and the user does not have to
Once done, this will remain across sessions and the user does not have to
check it again.

.. figure:: images/listings/disclaimer_checked.png
Expand Down Expand Up @@ -330,7 +366,7 @@ will be up to you to take these into account or not.
Listings
^^^^^^^^

When searching source extensions in the Extension Manager, JupyterLab displays the complete search result and
When searching source extensions in the Extension Manager, JupyterLab displays the complete search result and
the user is free to install any source extension. This is the :ref:`default_mode`.

To bring more security, you or your administrator can enable ``blocklists`` or ``allowlists``
Expand All @@ -350,7 +386,7 @@ mode. JupyterLab will check the extensions against the defined listings.


The following details the behavior for the :ref:`blocklist_mode` and the :ref:`allowlist_mode`.
The details to enable configure the listings can be read :ref:`listings_conf`.
The details to enable configure the listings can be read :ref:`listings_conf`.

.. _default_mode:

Expand All @@ -366,8 +402,8 @@ Blocklist mode
""""""""""""""

Extensions can be freely downloaded without going through a vetting process.
However, users can add malicious extensions to a blocklist. The extension manager
will show all extensions except for those that have
However, users can add malicious extensions to a blocklist. The extension manager
will show all extensions except for those that have
been explicitly added to the blocklist. Therefore, the extension manager
does not allow you to install blocklisted extensions.

Expand All @@ -392,18 +428,18 @@ your mouse on the question mark icon to read the instructions.
Allowlist mode
""""""""""""""

An allowlist maintains a set of approved extensions that users can freely
search and install. Extensions need to go through some sort of vetting process
before they are added to the allowlist. When using an allowlist, the extension manager
An allowlist maintains a set of approved extensions that users can freely
search and install. Extensions need to go through some sort of vetting process
before they are added to the allowlist. When using an allowlist, the extension manager
will only show extensions that have been explicitly added to the allowlist.

If you, or your administrator, has enabled the allowlist mode
JupyterLab will use the allowlist and only show extensions present
in the allowlist. The other extensions will not be show in the search result.

If you have installed an allowlisted extension and at some point
in time that extension is removed from the allowlist, the extension entry
in the installed list will be highlighted in red. It is recommended that
in time that extension is removed from the allowlist, the extension entry
in the installed list will be highlighted in red. It is recommended that
you uninstall it. You can move your mouse on the question mark icon to
read the instructions.

Expand All @@ -428,7 +464,7 @@ You or your administrator can use the following traits to define the listings lo
For example, to set blocked extensions, launch the server with ``--LabServerApp.blocked_extensions_uris=http://example.com/blocklist.json`` where ``http://example.com/blocklist.json`` is a JSON file as described below.

The details for the listings_request_options are listed
on `this page <https://2.python-requests.org/en/v2.7.0/api/#requests.request>`__
on `this page <https://2.python-requests.org/en/v2.7.0/api/#requests.request>`__
(for example, you could pass ``{'timeout': 10}`` to change the HTTP request timeout value).

The listings are json files hosted on the URIs you have given.
Expand Down Expand Up @@ -456,7 +492,7 @@ This is an example of a blocklist file.
}
In the following allowed extensions ``@jupyterlab/*`` will allow
In the following allowed extensions ``@jupyterlab/*`` will allow
all jupyterlab organization extensions.

.. code:: json
Expand All @@ -472,5 +508,3 @@ all jupyterlab organization extensions.
}
]
}
3 changes: 3 additions & 0 deletions setup.cfg
View file
Expand Up @@ -12,6 +12,9 @@ platforms = Linux, Mac OS X, Windows
keywords = ipython, jupyter
classifiers =
Development Status :: 5 - Production/Stable
Framework :: Jupyter
Framework :: Jupyter :: JupyterLab
Framework :: Jupyter :: JupyterLab :: 4
Intended Audience :: Developers
Intended Audience :: System Administrators
Intended Audience :: Science/Research
Expand Down

0 comments on commit 7fee5a2

Please sign in to comment.