Template Usage¶

Layout¶

The template generates a repository structure. The layout shown below represents the full set of files and directories that may be created by the template. Depending on the configuration choices you made during setup, some of these files or components may be omitted automatically.

$ tree
--> 100%
PROJECT ------------------------
├── .copier-answers.yml
├── .gitignore
├── .gitlab-ci.yml
├── .pre-commit-config.yml
├── .python-version
├── CHANGELOG.md
├── CITATION.cff
├── CONTRIBUTING.md
├── Dockerfile
├── Justfile
├── LICENSE
├── README.md
├── docker-compose.yml
├── environment.yml
├── myst.yml
├── pyproject.toml
├── uv.lock
├── src/PROJECT
│   └── __init__.py
└── notebooks
    ├── how-to-cite.md
    └── index.md

Justfile - Task Runner¶

The Justfile contains, so called recipes, which are predefined tasks or workflows to simplify common tasks. Here are a few examples. Run just to list all available recipes.

$ uv tool install rust-just

$ just
Available Recipes:
    test    # run the tests
    check   # run the linter and formatter

• just venv create a virtual environment
• just hooks to install pre-commit hooks
• just clean to remove build artifacts
• just docs to serve a local version of your cookbook
• just init to initialize a new repository (one time use only)

Pre-Commit¶

Git provides mechanisms to run scripts (so called hooks) before or after certain events. One of those events would be called pre-commit. As the name might suggest the pre-commit-hooks run before a commit is performed. When the hooks fail or error the commit is aborted.

There are tools, which provide a simple way of setting up predefined pre-commit-hooks. The most famous being pre-commit and a new rewrite of the same tool in rust prek.

The way to set up or use those pre-commit-hooks is defining the hooks in a file called .pre-commit-config.yaml. The current template already provides some default hooks, but they they can be removed or others be added.

The pre-commit-hooks only live on the users machine, and are not uploaded to gitlab. That means every user needs to install them whenever he clones the repository again.

This can be done by running:

uvx pre-commit install

Virtual Environment¶

The template stores project metadata, such as external dependencies, in a PEP 621 compliant pyproject.toml file. The Python Package Manager uv is used for managing dependencies, virtual environments and other metadata. Here are a few key commands to keep in mind:

• uv sync to create a .venv and install dependencies defined in pyproject.toml
• uv add to add dependencies to the project

Docker¶

Docker is used to provide a consistent, isolated environment for developing Jupyter Notebooks.

Start Docker¶

When available, simply run the following to start a Jupyter Lab instance:

• Start Jupyter Lab from a Docker container:

$ just docker-up

$ docker compose up

• Copy the Jupyter Lab URL from the logs and open it in your web browser to access the notebook interface.

Stop Docker¶

To stop and remove the container:

1. Stop the Docker container by pressing CTRL + C in the terminal where the container is running.
2. Remove the container and associated resources:

$ just docker-down

$ docker compose down

This Docker setup ensures a reproducible environment for cookbook authors, aligning with the project’s goal of uniform content development.