For contributors

You are welcome to contribute to the project either by requesting new topics, proposing ideas or getting involved in the development!

Submitting new talktorials

This is a step-by-step guide on how to submit new talktorials.

  1. Fork the repository:

  2. Ask us for your talktorial index (our notebooks are indexed with T001, T002, …).

  3. Clone your fork:

    git clone
  4. Change into the cloned/downloaded teachopencadd folder:

    cd teachopencadd
  5. Checkout a new branch with your initials, talktorial index, and talktorial short title (e.g. ab-t099-fingerprints):

    git checkout -b ab-t099-fingerprints
  6. Create toc-dev environment:

    # Create environment with dependencies
    mamba env create -f devtools/test_env.yml -n toc-dev
    # On MacOS with M1 chip you may need
    CONDA_SUBDIR=osx-64 mamba env create -f devtools/test_env.yml -n toc-dev
    # Activate enviroment
    conda activate toc-dev
    # Pip install teachopencadd in editable mode
    cd ..
    pip install -e teachopencadd
    cd teachopencadd
    # Interact with the talktorials via e.g. Jupyter Lab
    jupyter lab

    If you add new dependencies to devtools/test_env.yml, you will need to redo step 6.

  7. Make a copy of the following template folder using your talktorial index and short name (example here is T099_fingerprints:

    cp -r teachopencadd/talktorials/T000_template/ teachopencadd/talktorials/T099_fingerprints
  8. Replace all instances of T000_template or “T000 · Talktorial topic title” with your talktorial index and title.

    1. T099_fingerprints/talktorial.ipynb is the talktorial template (see the example here), within which you develope your new talktorial. Please read through the template before you start as it contains a lot of information about the content and style requirements.

    2. You do not need to worry about updating T099_fingerprints/ as we are autogenerating these READMEs with the first couple of sections of the notebook (see more details in Maintaining talktorials).

    3. As the names suggest, the folders T099_fingerprints/data/ and T099_fingerprints/images/ can be used to store input/output data and images. Whenever possible, avoid adding files and instead fetch data/images by URL. Ask us if in doubt.

  9. Push your new talktorial folder skeleton to your GitHub repository (replace T099_fingerprints and ab-t099-fingerprints with your own):

    # Add folder
    git add teachopencadd/talktorials/T099_fingerprints/
    # Commit changes
    git commit -m "T099: Add talktorial folder skeleton"
    # Push changes
    git push origin ab-t099-fingerprints
  10. Create the pull request (PR) with our PR template:

    1. Go to your fork and click “New pull request”.

    2. Select the following:

      • base repository: volkamberlab/teachopencadd and base: master

      • head repository: your-github-name/teachopencadd and compare: ab-t099-fingerprints

    3. Click “Create pull request”.

    4. When the PR description window opens, please copy-paste the content of this PR template into it.

  11. Read through the PR description TODOs and check in with us if you have questions. Note: Many bullet points have to do with our maintenance efforts (see more details in Maintaining talktorials).

  12. Get started with developing your talktorials. Add your changes to the PR by following the procedure in step 9.

  13. Ping us if you need help or are ready for the PR review. Thanks!

Updating talktorials

This is a step-by-step guide on how to update existing talktorials.

If you find an error in a talktorial or wish to extend the content of one, please follow these steps (example: updating talktorial T002_compound_adme):

  1. Fork and clone the teachopencadd repository and checkout a new branch as described in steps 1-5 in Submitting new talktorials, while step 2 refers to the index of the talktorial you wish to update, e.g. T002_compound_adme, and your new branch should be something descriptive like ab-t002-extend-adme-theory.

  1. Set up environment as described in step 6 in Submitting new talktorials.

  1. Push your new branch to your GitHub repository (replace T002_compound_adme and ab-t002-extend-adme-theory with your own):

    # Add folder
    git add teachopencadd/talktorials/T002_compound_adme/
    # Commit changes
    git commit -m "T002: Extend ADME theory"
    # Push changes
    git push origin ab-t002-extend-adme-theory
  2. Create PR as described in steps 10 and 11 in Submitting new talktorials. Some PR bullet points might not apply to your case, please use ~ (e.g. ~some bullet point~) to strike those through.

  3. Ping us if you need help or are ready for the PR review. Thanks!

Maintaining talktorials

This is an overview about our TeachOpenCADD maintenance efforts.

  • Our environment file satisfies the dependencies for all TeachOpenCADD talktorials. This format might change in the future as discussed here.

  • Our GitHub Actions CI setup file contains:

    • Notebook tests (pytest), which check if the notebook runs without errors and if cells flagged with # NBVAL_CHECK_OUTPUT produce the same output in the CI run as saved within the talktorial.ipynb file. Check under jobs.test the tested operating systems and Python versions.

    • Notebook formatting (black-nb), check under jobs.format:

      # Apply formatting to all talktorials
      black-nb -l 99 teachopencadd/talktorials/T*/talktorial.ipynb
    • Autogenerated READMEs, check under jobs.readmes:

      # Autogenerate all talktorials' README
      for path in teachopencadd/talktorials/T*/talktorial.ipynb; do
          python devtools/ --output $path
  • Our TeachOpenCADD website:

  • We are cutting new releases as described in this Discussion entry.

  • Our teachopencadd package lives with conda-forge:

    • Whenever we cut a new GitHub release, we have to also cut a new conda release.

    • Refer to “Maintaining packages” and these notes for instructions on how to do this and ask @dominiquesydow for help. In order to cut a new conda release, you will need to update the recipe within our teachopencadd feedstock.