Template Useage¶

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.

// Display the project files
$ tree
PROJECT ------------------------ # your freshly created cookbook
├── .copier-answers.yml -------- # Copier Answer to update project
├── .gitignore ----------------- #
├── .gitlab-ci.yml ------------- # Gitlab CI Config
├── .pre-commit-config.yml ----- #
├── .python-version ------------ #
├── CHANGELOG.md --------------- #
├── CITATION.cff --------------- #
├── CONTRIBUTING.md ------------ #
├── Dockerfile ----------------- #
├── Justfile ------------------- # Taskrunner
├── LICENSE -------------------- #
├── README.md ------------------ #
├── docker-compose.yml --------- #
├── environment.yml ------------ #
├── myst.yml ------------------- #
├── pyproject.toml ------------- # Project Config
├── uv.lock -------------------- #
│
├── src/PROJECT ---------------- # Python Package
│   └── __init__.py ------------ #
└── notebooks ------------------ # Documentation pages
    ├── 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.

// Install just taskrunner from pypi
$ uv tool install rust-just
---> 100%
// Run any Just Recipe
$ 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)

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:

// Run a docker container
$ just docker-up

// Run a docker container
$ 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:

// Stop a docker container gracefully
$ just docker-down

// Stop a docker container gracefully
$ docker compose down

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