Quansight-Labs / jupyterlab-accessible-themes

β™ΏοΈπŸŽ¨ An access-centred implementation of the JupyterLab default themes
BSD 3-Clause "New" or "Revised" License
2 stars 1 forks source link
Jupyter Accessibility logo


JupyterLab accessible themes

Information Links
Project OSI License clickable badge - BSD-3 Project backlog clickable badge
Tools Launch on Binder clickable badge

Welcome to the JupyterLab accessible themes' repository πŸ‘‹πŸ½. To learn more about the broader accessibility initiatives within Jupyter, check the jupyter/accessibility repository.

This repository defines a set of accessible themes according to WCAG color standards. Please note that some themes are optimized for colorblindness and/or high contrast. Inside the README of each theme, you will find detailed information about the colors, their purpose and reference links from the original authors.

About the themes

Font

=======

All the themes are using the Atkinson Hyperlegible font, which focuses on letter form distinction to increase character recognition, ultimately improving readability.

This font can only be changed for the Markdown viewer and the Terminal. You will need to make these changes from the Advanced settings editor in the JupyterLab UI:

  1. Select the Settings option in the menu bar.
  2. Go to Markdown viewer settings, and type the font family that you want to use.
  3. To change the Terminal font, scroll down to Terminal settings and type the name of the font family.

Requirements πŸ“¦

Installing the extension πŸ—

You can install the extension using pip:

pip install jupyterlab-accessible-themes

If you prefer conda:

conda install -c conda-forge jupyterlab-accessible-themes

# alternatively you can use mamba
mamba install jupyterlab-accessible-themes

After installing the extension, open JupyterLab, go to the top menu bar, go to Settings > Theme, and choose one of the themes provided by this extension.

choose an accessible theme from Settings > Theme in the JuptyerLab top menu bar

Uninstalling the extension 🧽

To remove the extension you can run the following command:

# if installed with pip
pip uninstall jupyterlab-accessible-themes

# if using conda
conda uninstall jupyterlab-accessible-themes

Contributing to JupyterLab accessible themes πŸ™‹πŸ½β€β™€οΈ

Installing the development version πŸ’»

Pre-requisites

  1. You will need to have NodeJS installed on your local computer to build the extension package.
  2. Python >= 3.8 and pip.

Building and linking the extension

Note The jlpm command is JupyterLab's pinned version of yarn that is installed with JupyterLab. You may useyarn or npm in lieu of jlpm in the commands below.

  1. Clone this repository to your local computer:

    git clone https://github.com/Quansight-Labs/jupyterlab-accessible-themes.git
  2. Change to the jupyterlab-accessible-themes directory:

    cd jupyterlab-accessible-themes
  3. Optional but recommended - Create and activate a development environment with conda:

    # Create environment named `jupyterlab-accessible-themes`
    conda create -n jupyterlab-accessible-themes
    conda activate jupyterlab-accessible-themes
  4. Install JupyterLab and NodeJS if not installed:

    # Install node and jupyterlab from conda-forge
    conda install -c conda-forge 'nodejs>16' 'jupyterlab<4'
  5. Install the node dependencies and build the extension:

    # Install node dependencies
    jlpm install
    
    # Compile packages before linking to Jupyterlab development version
    jlpm build
  6. Install the package in development mode:

    pip install -e .
  7. Now you'll need to link the development version of the extension to JupyterLab and rebuild the Typescript source:

    # Link your development version of the extension with JupyterLab
    jupyter labextension develop . --overwrite
  8. On the first installation, or after making some changes, to visualize them in your local JupyterLab re-run the following command:

    # Rebuild extension Typescript source after making changes
    jlpm build
  9. Run JupyterLab and check that the installation worked:

# Run JupyterLab
jupyter lab

Important Once everything is installed, you will need to select the theme inside JupyterLab via the main menu Settings > Theme.

Further development tips

πŸ” You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.

# Watch the source directory (JupyterLab accessible themes) in one terminal, automatically rebuilding when needed
# Can use yarn or npm depending on your preference
jlpm watch

# Run JupyterLab in another terminal
jupyter lab

With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab instance. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).

By default, the jlpm build command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:

jupyter lab build --minimize=False

Pre-commit hooks 🧹

This repository uses the prettier pre-commit hook to standardize our YAML and markdown structure.

  1. Before you can run the hooks, you need to install the pre-commit package manager:

    # using pip
    pip install pre-commit
    
    # if you prefer using conda
    conda install -c conda-forge pre-commit
  2. From the root of this project, install the git hook scripts:

    # install the pre-commit hooks
    pre-commit install
  3. Optional- run the hooks against the files in this repository

    # run the pre-commit hooks
    pre-commit run --all-files

Uninstalling the development version 🧽

  1. Remove the extension:

    pip uninstall jupyterlab-accessible-themes
  2. In development mode, you will also need to remove the symlink created by jupyter labextension develop command. To find its location, you can run jupyter labextension list to figure out where the labextensions folder is located. Then you can remove the symlink named jupyterlab-accessible-themes within that folder.

Testing the extension βœ…

Frontend tests

This extension is using Jest for JavaScript code testing.

To execute the tests run the following command:

jlpm
jlpm test

Integration tests

This extension uses Playwright for the integration tests (aka user-level tests). More precisely, the JupyterLab helper Galata is used to handle testing the extension in JupyterLab. More information is provided within the ui-tests README.

Packaging the extension πŸ“¦

Detailed instructions for creating jupyterlab-accesible-themes can be found in the RELEASE file.

License πŸ“–

This project is licensed under the BSD-3-Clause license.

Acknowledgements πŸ™πŸΌ

We want to thank the following sources for being the source of inspiration for one or more themes that are available in this repository,