Contents

Contributing

Setup

nbgitpuller is a jupyter extension that works with both the classic Notebook Server, and the newer Jupyter Server. Hence, nbgitpuller can be developed locally without needing a JupyterHub.

  1. Fork the nbgitpuller repository and git clone it to your local computer.

  2. Inside the nbgitpuller clone on your local machine, setup a virtual environment to do development in

    python3 -m venv venv
source venv/bin/activate

  3. Install development time dependencies in this virtual environment

    pip install -r dev-requirements.txt

  4. Install nbgitpuller with its dependencies in this virtual environment

    pip install -e .

  5. Install the NodeJS dependencies from package.json.

    npm install

  6. Create the JS and CSS bundles.

    npm run webpack

  7. Enable the nbgitpuller extension:

    • as a jupyter serverextension (classic Notebook Server extension)

      jupyter serverextension enable --sys-prefix nbgitpuller

    • as a jupyter server extension

      jupyter server extension enable --sys-prefix nbgitpuller

  8. Start the notebook server:

    • You can either start the classical Notebook server. This will open the classic notebook in your web browser, and automatically authenticate you as a side effect.

      jupyter notebook

    • Or you can start the new Jupyter Server.

      jupyter server

      This won’t open any notebook interface, unless you don’t enable one (nbclassic or jupyterlab) as a jupyter server extension.

      jupyter server extension enable --sys-prefix nbclassic

      or

      jupyter server extension enable --sys-prefix jupyterlab

  9. You can now test nbgitpuller locally, by hitting the /git-pull url with any of the URL query parameters. For example, to pull the data-8/textbook repository’s gh-pages branch, you can use the following URL:

    http://localhost:8888/git-pull?repo=https://github.com/data-8/textbook&branch=gh-pages

  10. If you make changes to nbgitpuller’s python code, you need to restart the jupyter notebook process (started in step 5) to see your changes take effect. This is not needed if you are only working on the javascript or css.

Running the flake8 linter

flake8 is used to validate python coding style. The flake8 config is in .flake8, and is not super strict. You should be able to run flake8 in the root directory of the repository to get a list of issues to be fixed.

Running tests

pytest is used to run unit and integration tests, under the tests/ directory. If you add new functionality, you should also add tests to cover it. You can run the tests locally with py.test tests/

Building documentation

sphinx is used to write and maintain documentation, under the docs/ directory. If you add any new functionality, you should write documentaiton for it as well. A mix of reStructuredText and MyST Markdown is used to write our documentation, although we would like to migrate purely to MyST markdown in the future.

  1. Install the packages needed to build the documentation

    pip install -r docs/doc-requirements.txt

  2. Build the documentation by using make inside the docs folder. This will internally call sphinx

    cd docs
make html

  3. Preview the documentation by opening _build/html/index.html file in your browser. From inside the docs folder, you can run either open _build/html/index.html (on MacOS) or xdg-open _build/html/index.html to quickly open the file in the browser.

  4. You can run make html again after making further changes to see their effects.