Project Makefile using Pip Tools

.PHONY: help init jupyter-notebook jupyter-lab clean clean-venv distclean

PYTHON = .venv/bin/python

help:   ## Show this help
	@grep -E '^([a-zA-Z_-]+):.*## ' $(MAKEFILE_LIST) | awk -F ':.*## ' '{printf "%-20s %s\n", $$1, $$2}'

$(PYTHON): requirements.in
	python3 -m venv .venv
	$@ -m pip install --upgrade pip
	$@ -m pip install pip-tools
	@touch $@  # mark updated

requirements.txt: $(PYTHON) requirements.in
	$(PYTHON) -m piptools compile -o $@ requirements.in
	$(PYTHON) -m piptools sync
	@touch $@  # mark updated

init: requirements.txt  ## Create the virtual project environment

jupyter-notebook: requirements.txt  ## Run a Jupyter notebook server
	jupyter notebook

jupyter-lab: requirements.txt  ## Run a Jupyter lab server
	jupyter lab

clean: ## Remove generated files

clean-venv: ## Remove environment
	rm -rf .venv

distclean: clean  clean-venv  ## Restore clean repository state
	rm -rf *.ipynb  # if using jupytext
	rm -f requirements.txt
	rm -rf .ipynb_checkpoints

Notes:

• The help target could also be implemented with a Python script
• The version of Python used to create the .venv folder is the version of Python to be used for the project. Consider using, e.g., python3.10 instead of python3.
• Since pip-tool is installed automatically into .venv, it is not a dependency to bootstrap the project.
• Instead of requirements.in, requirements could also be specified in pyproject.toml, see the pip-tools documenrtation
• The requirements.in file must include ipykernel (the "project kernel")
• The jupyter executable is not (and should not be) part of the .venv. Instead, there should be a single "site" installation of Jupyter.
• To make the project kernel available to the site Jupyter installation, make sure that python-localvenv-kernel is installed into the same environment as Jupyter. All notebooks should use this kernel.
• The clean target should be used to remove, e.g., __pycache__ files, if applicable.
• The distclean target should remove *.ipynb files only if the Jupytext extension is used. Note that this removes the output of all notebooks. If your notebooks take a long time to run, take steps as to not accidentally delete the notebooks.
• When the project is "stable" / "finished", consider adding requirements.txt to source control (and then do not remove it in make distclean)

With an installable kernel

If it is not possible to install python-localvenv-kernel, the project kernel must be installed into the user's Jupyter data directory. To this end, we can add install and uninstall targets:

.PHONY: help init install uninstall jupyter-notebook jupyter-lab clean clean-venv distclean

PYTHON = .venv/bin/python

help:   ## Show this help
	@grep -E '^([a-zA-Z_-]+):.*## ' $(MAKEFILE_LIST) | awk -F ':.*## ' '{printf "%-20s %s\n", $$1, $$2}'

$(PYTHON): requirements.in
	python3 -m venv .venv
	$@ -m pip install --upgrade pip
	$@ -m pip install pip-tools
	@touch $@  # mark updated

requirements.txt: $(PYTHON) requirements.in
	$(PYTHON) -m piptools compile -o $@ requirements.in
	$(PYTHON) -m piptools sync
	@touch $@  # mark updated

init: $(PYTHON)  ## Create the virtual project environment

install: $(PYTHON) ## Install Jupyter kernel into user environment
	$< -m ipykernel install --user --name my-project-name --display-name "My Project Name"

uninstall: ## Remove Jupyter kernel from user environment
	jupyter kernelspec remove -f my-project-name || true

jupyter-notebook: install  ## Run a Jupyter notebook server
	jupyter notebook --debug --no-browser

jupyter-lab: install  ## Run a Jupyter lab server
	jupyter lab --debug --no-browser

clean: ## Remove generated files

clean-venv: uninstall  ## Remove environment
	rm -rf .venv

distclean: clean clean-venv  ## Restore clean repository state
	rm -f *.ipynb  # if using jupytext
	rm -f requirements.txt
	rm -rf .ipynb_checkpoints

Note that install becomes a prerequisite for make jupyter-notebook and make jupyter-lab, and uninstall becomes a prerequisite for make clean-venv.