Contributing to jupyter/accessibility¶

Code of Conduct¶

This project follows the Jupyter Code of Conduct.

Goal¶

To facilitate improving the accessibility of interactive computing, we are trying to make it easy to:

capture the state of an accessibility feature across number of separate Jupyter repositories at different states of development as pull requests

deploy them together on Binder to share with people for testing

assess them on GitHub Actions to provide reports, raw data, and feedback

work as a team to get the pull requests merged

show progress towards an accessibility Roadmap

Core Workflow¶

get a free GitHub account
make one (or more) pull requests to one (or more) Jupyter repositories
make a pull request to jupyter/accessibility:ci that changes repos.toml to include the pull requests from step 2
- the pull request target should be the ci branch
construct the appropriate Binder link and paste the Markdown in (all of) the pull request(s)
gather and discuss findings
update the upstream pull requests
repeat steps 3+ as needed
get upstream pull requests merged

Why is this so complicated?¶

Improving the accessibility of a Jupyter client may require touching many repositories:

the client code itself
dependencies of the client
the underlying server code, and its dependencies
formal specifications such as the Jupyter Kernel Messaging or the Jupyter Notebook Format
- changes at this level often require a new Jupyter Enhancement Proposal (JEP)

Each component likely has its own developer workflows and culture. In this repository, we’ve tried to collect the workflows in a declarative, productive way, that allows trying out Code From The Future, without blocking review until every pull request merged.

On Binder¶

Reproduce locally with doit app docs

To meet some of the above challenges, this repository’s interactive state on Binder is composed of a full live development environment made of the (hopefully) harmonious union of different repositories at different states of development from GitHub branches and pull requests.

Implemented in repo2docker’s postBuild stage, this allows for creating very specific environments without re-inventing too much.

On GitHub Actions¶

Reproduce locally with doit report

The GitHub Actions workflow performs many of the same steps as Binder, but also:

runs pa11y-ci against all generated content
uploads reports as artifacts which are available to any GitHub user

On Your Computer¶

You can do all of the things that happen on Binder and GitHub Actions on your computer.

Get Miniforge for conda
- if your computer runs Windows, please ensure you:
  - install conda on short path, e.g. c:\mf
  - clone this repo to a short path, e.g. c:\git\a11y

Make an environment like the one in Binder

conda env update .binder/environment.yml
conda activate a11y

List all the doit tasks
```
doit list --all --status
```
Try out different doit tasks! The most fun one is:
```
doit start
```
which actually… starts JupyterLab!

Under the Hood¶

doit¶

The workhorse of this approach is doit. It is a python-based tool that manages:

running tasks
- in the right order
  - when (parts of) files change

Why Not Just (make|docker|pants|scons|bazel|grunt|…)?¶

In building and delivering complex environments, we’ve found doit offers a mix of portability, expressiveness, and productivity. Being python-based we can be relatively sure it’s going to work anywhere Jupyter works. Despite it’s quirks, python is good at reading strings and running processes. Ensuring work isn’t repeated is really important when welding together n development workflows.

PRs welcome to add alternative workflows that meet all these criteria!

Jupyter Accessibility

Contributing to jupyter/accessibility

Contents