Appendix B — Contributing

Thank you for considering contributing to the Animals In Motion project! We welcome contributions in various forms, including bug reports, requests for content improvement, as well as new tutorials or case studies.

B.1 Setting up the development environment

Begin by cloning the repository and navigating to its root directory:

git clone https://github.com/neuroinformatics-unit/animals-in-motion.git
cd animals-in-motion

We use conda to manage dependencies. First, create a development environment using the environment-dev.yaml file, and activate it:

conda env create -n animals-in-motion-dev -f environment-dev.yaml
conda activate animals-in-motion-dev

To enable the pre-commit hooks, run the following command once:

pre-commit install

This is a Quarto book project, with its source code located in the book/ directory. We refer you to the Quarto documentation for more information on how books are structured and configured.

To render/preview the book locally, you’ll need the Quarto CLI installed, as well as the VSCode Quarto extension

You will also need to make sure that the QUARTO_PYTHON environment variable is set to the path of the python executable in the development conda environment. This guarantees that the Quarto CLI will use the correct Python interpreter when rendering the book.

export QUARTO_PYTHON=$(which python)

Then, you can render the book using:

quarto render book
# or if you want to run executable code blocks before rendering to html
quarto render book --execute

You can view the rendered book by opening the book/_book/index.html file in your browser.

B.2 Authoring content

Book chapters are written primarily as Quarto Markdown files (.qmd). These can contain a mix of narrative and interactive content, such as code exercises. See Quarto computations > Using Python to learn more about executable code blocks.

We recommend using the Quarto VSCode extension for authoring and previewing content.

Alternatively, you may also use JupyterLab, with Jupyter Notebooks (.ipynb) as source files—see Quarto tools > JupyterLab for more information.

The chapter source files reside in the book/ directory and have to be linked in the book/_quarto.yml file for them to show up. See Book Crossrefs on how to reference other chapters.

Bibliographical references should be added to the book/references.bib file in BibTeX format. See Quarto authoring > Citations for more information.

In general, cross-referencing objects (e.g. figures, tables, chapters, equations, citations, etc.) should be done using the @ref syntax, e.g. See @fig-overview for more details.

B.2.1 Adding answers to exercises

This book is configured to be rendered with or without answers to exercises, using Quarto profiles.

  • The _quarto.yml file defines the “default” profile for the book, which does not show the answers to exercises.
  • The _quarto-answers.yml file defines the “answers” profile, which is identical to the “default” profile, but also includes solutions to code exercises.

To add answers to code exercises, please enclose them in a block of the following form:

::: {.content-visible when-profile="answers"}

::: {.callout-tip title="Click to reveal the answers" collapse="true"}

Write your solution here.

:::

:::

Then you can control whether the answers are shown or not by passing the appropriate Quarto profile to the quarto render command:

quarto render book --execute --profile default  # equivalent to no profile
quarto render book --execute --profile answers

You can achieve the same effect by setting the QUARTO_PROFILE environment variable before rendering the book:

export QUARTO_PROFILE=answers
quarto render book --execute

In general, it’s most convenient to show the answers while you are developing the content, and then hide them to preview the book as a student would see it.

See the Section B.4 for more information on how to create releases with or without answers.

B.3 Pre-commit hooks

We use pre-commit to run checks on the codebase before committing.

Current hooks include:

  • codespell for catching common spelling mistakes.
  • markdownlint for (Quarto) Markdown linting and formatting.
  • ruff for code linting and formatting.

These will prevent code from being committed if any of these hooks fail. To run all the hooks before committing:

pre-commit run  # for staged files
pre-commit run -a  # for all files in the repository

B.4 Versioning and releasing

We use Calendar Versioning (CalVer) and specifically the YYYY.0M scheme (e.g. 2025.08 for August 2025).

To create a new release, first update the book/index.qmd file. Specifically, add two rows like the following to the “Versions” table:

| `2025.08` | version used for the inaugural workshop in August 2025 |
| `v2025.08-answers` | same as `v2025.08` but with answers to exercises |

You also need to create a new tag in the vYYYY.0M format (e.g. v2025.08) and push it to the repository. Don’t forget the v prefix for the tag name!

For example:

git tag v2025.08
git push origin --tags

B.5 Continuous integration (CI)

The CI workflow is defined in the .github/workflows/build_and_deploy.yaml file and can be triggered by:

  • Pushes to the main branch
  • Pull requests
  • Releases, i.e. tags starting with v (e.g., v2025.08)
  • Manual dispatches

The workflow is built using GitHub actions and includes three jobs:

  • linting: running the pre-commit hooks;
  • build: rendering the Quarto book with and without answers, and uploading the rendered artifacts;
  • deploy: deploying the book artifact(s) to the gh-pages branch (only for pushes to the main branch and releases).

Each release version is deployed to a folder in the gh-pages branch, with the same name as the release tag (e.g., v2025.08). This is accompanied by a vYYYY.0M-answers folder containing a version of the book with answers to exercises (e.g. v2025.08-answers).

There’s also a special folder called dev that is deployed for pushes to the main branch. This folder always includes the answers to exercises.

B.5.1 Previewing the book in CI

We use artifact.ci to preview the book that is rendered as part of our CI workflow. This is useful to check that the book renders correctly before merging a PR. To do so:

  1. Go to the “Checks” tab in the GitHub PR.
  2. Click on the “Build and Deploy Quarto Book” section on the left.
  3. If the “Build Quarto book” action is successful, a summary section will appear under the block diagram with a link to preview the built documentation.
  4. Click on the link and wait for the files to be uploaded (it may take a while the first time). You may be asked to sign in to GitHub.
  5. Once the upload is complete, look for book/_book-answers/index.html under the “Detected Entrypoints” section.