How to add a new talktorial based on our template?

[jaimergp]

How to start

Replace example names as needed:

git clone https://github.com/volkamerlab/teachopencadd.git
cd teachopencadd/
# or... git pull on master
git checkout -b ab-099-title  # ab = your initials; 099 = your talktorial index; title = short talktorial title 
git commit --allow-empty -m "Start branch"
git push --set-upstream origin ab-099-title

# Now go to the suggested URL and create the PR using the suggested template
# If the template is not there, copy it from this issue: https://github.com/volkamerlab/TeachOpenCADD/issues/41

# Back to the CLI to set up the environment
mamba env create -f devtools/test_env.yml
conda activate teachopencadd
jupyter labextension install @ijmbarr/jupyterlab_spellchecker
jupyter lab

Now you can start working on your talktorial!

Render the website locally

Once your talktorial ready, check how it renders in HTML.

cd docs
make html
cp -r talktorials/images/ _build/html/talktorials/images
cd _build/html
# open index.html on your browser:
xdg-open index.html
# or under windows: explorer.exe index.html
# or under MacOS: open index.html

If your notebook does not appear, you need to add the nblink forwarder in docs/notebooks. Copy paste an existing ones and update paths accordingly!

PR template

Create a PR using this template. Ping us as reviewer once you'd like feedback on the talktorial.

https://github.com/volkamerlab/teachopencadd/blob/master/.github/PULL_REQUEST_TEMPLATE/talktorial_review.md

[dominiquesydow]

Do we want everyone to push only notebooks without executed cells, @jaimergp? If so, we should add this to the checklist.

[jaimergp]

It's ok for now. We'll clear everything before merge anyway!

[t-kimber]

Super nice, super clear! Love the template :)

Just a note for MAC users:
in the Render the website locally section, the command which will render the website is open index.html (and not xdg-open index.html).

[t-kimber]

What do you think if we add to the checklist a bullet point concerning populating the README.md in each talktorial folder (title, aim, learning goals, categories) ?

[jaimergp]

What do you think if we add to the checklist a bullet point concerning populating the README.md in each talktorial folder (title, aim, learning goals, categories) ?

This is going to be automated with a little script. Do take a look at <Talktorial>/data/README.md, tho 😬

[t-kimber]

Just a small detail:

since the reviews branch no longer exists, it might be an idea to change the todo list with package , e.g. git checkout package instead of git checkout reviews?

[dominiquesydow]

Thanks, @jaimergp, for updating the template for the next round of talktorial refactoring :)

[Old-Shatterhand]

Update for the environment file in the introduction:
conda env create -f devtools/conda-envs/test_env.yml
has to be changed to
conda env create -f devtools/test_env.yml.

[dominiquesydow]

Done, thank you!

[Old-Shatterhand]

I have another suggestion: I've been setting up the conda environment. On my notebook the conda solver for the dependencies failed as it run out of RAM. Using mamba instead of conda is way faster. Maybe this is an idea to improve and speedup the installation.

[dominiquesydow]

Definitely agreed, we recommend mamba in our official installation instructions: https://projects.volkamerlab.org/teachopencadd/installing.html#install-from-the-latest-development-snapshot

Are you part of the TeachOpenCADD hackathon with @AndreaVolkamer today?

[dominiquesydow]

I think it would be nice to replace this Discussion with updated instructions and put them to our contributor section on the website (see link above).

I was planning on adding a proper contributor guide (here) but as you can see from the PR I did not get far as of now.

[AndreaVolkamer]

Yes, this comes from the hackathon group :)