Contents

Contributing

Setup

nbgitpuller is a jupyter serverextension, and hence 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. Enable the nbgitpuller jupyter serverextension

    jupyter serverextension enable --sys-prefix nbgitpuller

  6. Start the notebook server. This will open the classic notebook in your web browser, and automatically authenticate you as a side effect.

    jupyter notebook

  7. 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-sync?repo=https://github.com/data-8/textbook&branch=gh-pages

  8. 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.

Installation Automatic Merging Behavior