CONTRIBUTING.rst

General Jupyter contributor guidelines

If you're reading this section, you're probably interested in contributing to Jupyter. Welcome and thanks for your interest in contributing!

Please take a look at the Contributor documentation, familiarize yourself with using the terminado, and introduce yourself on the mailing list and share what area of the project you are interested in working on.

For general documentation about contributing to Jupyter projects, see the Project Jupyter Contributor Documentation.

Setting Up a Development Environment

Installing Terminado

Run the the following steps to set up a local development environment:

pip install --upgrade setuptools pip
git clone https://github.com/jupyter/terminado
cd terminado
pip install -e ".[test]"

If you are using a system-wide Python installation and you only want to installed for you, you can add --user to the install commands.

Code Styling

terminado has adopted automatic code formatting so you shouldn't need to worry too much about your code style. As long as your code is valid, the pre-commit hook should take care of how it should look. pre-commit and its associated hooks will automatically be installed when you run pip install -e ".[test]"

To install pre-commit manually, run the following:

pip install pre-commit
pre-commit install

You can invoke the pre-commit hook by hand at any time with:

pre-commit run

which should run any autoformatting on your code and tell you about any errors it couldn't fix automatically. You may also install [black integration](https://github.com/psf/black#editor-integration) into your text editor to format code automatically.

If you have already committed files before setting up the pre-commit hook with pre-commit install, you can fix everything up using pre-commit run --all-files. You need to make the fixing commit yourself after that.

Running Tests

Install dependencies:

pip install -e .[test]

To run the Python tests, use:

pytest

Building the Docs

To build the docs, run the following:

cd doc
pip install -r requirements.txt
make html

After that, the generated HTML files will be available at build/html/index.html. You may view the docs in your browser.

You can automatically check if all hyperlinks are still valid:

make linkcheck

Windows users can find make.bat in the docs folder.

You should also have a look at the Project Jupyter Documentation Guide.