nbgitpuller is a jupyter serverextension, and hence can be developed locally without needing a JupyterHub.
Fork the nbgitpuller repository and
git cloneit to your local computer.
Inside the nbgitpuller clone on your local machine, setup a virtual environment to do development in
python3 -m venv venv source venv/bin/activate
Install development time dependencies in this virtual environment
pip install -r dev-requirements.txt
Install nbgitpuller with its dependencies in this virtual environment
pip install -e .
Enable the nbgitpuller jupyter serverextension
jupyter serverextension enable --sys-prefix nbgitpuller
Start the notebook server. This will open the classic notebook in your web browser, and automatically authenticate you as a side effect.
You can now test nbgitpuller locally, by hitting the
/git-pullurl with any of the URL query parameters. For example, to pull the data-8/textbook repository’s
gh-pagesbranch, you can use the following URL:
If you make changes to nbgitpuller’s python code, you need to restart the
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.
pytest is used to run unit and integration tests,
tests/ directory. If you add new functionality, you should also add
tests to cover it. You can run the tests locally with
sphinx is used to write and maintain documentation, under
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.
Install the packages needed to build the documentation
pip install -r docs/doc-requirements.txt
Build the documentation by using
docsfolder. This will internally call
cd docs make html
Preview the documentation by opening
_build/html/index.htmlfile in your browser. From inside the
docsfolder, you can run either
open _build/html/index.html(on MacOS) or
xdg-open _build/html/index.htmlto quickly open the file in the browser.
You can run
make htmlagain after making further changes to see their effects.