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