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.
Fork the nbgitpuller repository and
git clone
it 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 .
Install the NodeJS dependencies from package.json.
npm install
Create the JS and CSS bundles.
npm run webpack
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
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
orjupyterlab
) as a jupyter server extension.jupyter server extension enable --sys-prefix nbclassic
or
jupyter server extension enable --sys-prefix jupyterlab
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’sgh-pages
branch, you can use the following URL:http://localhost:8888/git-pull?repo=https://github.com/data-8/textbook&branch=gh-pages
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.
Install the packages needed to build the documentation
pip install -r docs/doc-requirements.txt
Build the documentation by using
make
inside thedocs
folder. This will internally callsphinx
cd docs make html
Preview the documentation by opening
_build/html/index.html
file in your browser. From inside thedocs
folder, you can run eitheropen _build/html/index.html
(on MacOS) orxdg-open _build/html/index.html
to quickly open the file in the browser.You can run
make html
again after making further changes to see their effects.