Contribution

Found a problem in one of the tutorials or with this website? Please let us know by opening an issue on GitHub. You are also very welcome to contribute a tutorial or a research page yourself.

Add a tutorial or research page

Contributions to this website can be written as Jupyter notebooks (.ipynb) or Quarto documents (.qmd). A tutorial should explain a useful Tequila feature or workflow, while a research page can present an application of Tequila in a research project.

Set up the website locally

First, install Git and Quarto. The repository already contains an environment.yml file with the Python packages used by the website. From the repository root, create and activate the environment with:

conda env create -f environment.yml
conda activate BlogQA
python -m ipykernel install --user --name BlogQA --display-name "Python (BlogQA)"

If the environment already exists, update it instead:

conda env update -f environment.yml --prune
conda activate BlogQA

You can then build and preview the website locally:

quarto preview

Quarto prints the local preview address in the terminal and automatically refreshes the page when you save a change. If your notebook needs an additional package that is not part of environment.yml, install it in the BlogQA environment and mention it in your pull request.

Create your contribution

Create one folder for your contribution in the appropriate section:

  • tutorials/<your-tutorial-name>/ for a tutorial
  • research/<your-project-name>/ for a research page

Keep the notebook or Quarto file and all files it needs, such as images, data, and a bibliography, together in this folder. Use relative paths so that the page also works after publication.

The first paragraph is shown as a short preview on the overview page. It should therefore introduce the topic in plain language before the tutorial begins with equations or code.

Place a YAML header like the following at the beginning of the notebook or Quarto document:

---
title: "A clear title for your contribution"
author: "Your full name"
date: "yyyy-mm-dd"
categories: [code]
image: "preview.png"
image-width: "1cm"
image-height: "1cm"
format:
  html:
    code-fold: false
jupyter: blogqa
---

The jupyter entry is needed for notebooks and for Quarto documents that execute Python code. You can omit it from a purely textual .qmd file. Set code-fold: true if long implementation cells should be collapsed by default.

A preview image makes the contribution easier to recognize on the overview page. You can use Preview_Image.png or Preview_Image.key from the repository root as a starting point, or create your own image with the same general proportions.

Submit your contribution

  1. Fork the Tequila tutorials repository to your own GitHub account and clone your fork.

  2. Add the original repository as the upstream remote if it is not configured yet:

    git remote add upstream https://github.com/tequilahub/tequila-tutorials.git

  3. Fetch the latest version and create a new branch from upstream/main:

    git fetch upstream
git switch -c my-contribution upstream/main

  4. Add your contribution in its own folder under tutorials/ or research/.

  5. Run quarto preview and check the page itself as well as its card on the Tutorials or Research overview page.

  6. Review git status, then commit only the files that belong to your contribution:

    git add tutorials/<your-tutorial-name>
git commit -m "Add tutorial on <topic>"

    For a research page, use the corresponding folder under research/.

  7. Push the branch to your fork:

    git push -u origin my-contribution

  8. Open a pull request from your branch to the main branch of tequilahub/tequila-tutorials.

Please use a separate branch and pull request for each independent contribution. This keeps the review focused and makes later changes easier to manage.

If you are planning a larger change, it is a good idea to open an issue first so that we can coordinate it with ongoing work. Changes to the Tequila library itself belong in the main Tequila repository, while examples and research applications are a good fit for this tutorial website.