'code' folder should be re-established/replaced

[tobyhodges]

@bobturneruk in #221:

some of the code used to generate figures was taken out of the main branch when the repo was upgraded to workbench. It may be worth having a separate issue on this, dealing with where such code should sit in the current repo structure e.g. instructor notes. This would be relevant to any code added resolving this issue not to be run by learners.

[tobyhodges]

I would propose that we recreate a /code directory.

That said, I quite like the idea of including the code for plots as inline Instructor Notes (where that code is not part of the lesson content). If we do take that approach, we should make sure those notes have headings that clearly indicate what they contain.

[bobturneruk]

I like the latter idea. It will encourage us to maintain parity with the figures. I guess details on how to make an inline instructor note are in the workbench docs.

[tobyhodges]

Yes, here: https://carpentries.github.io/sandpaper-docs/episodes.html#instructor-notes

You might also like this helpful video, featuring a lesson repository you may be familiar with 😉

[zkamvar]

The code folder was removed in #222, before the transition.

My 2 cents: if the code directory is intended to generate figures for the lesson by maintainers, but not instructors or learners, then it's best to create it at the top level and it will not be included in the rendered lesson site.

if, however you want to include the code as part of the repository, then it should live in the episodes/files folder and you can refer to the file in the episode with a relative link (e.g. [RectMask.py](files/04-drawing/RectMask.py)), which will be valid on The Workbench AND when viewing the markdown preview on GitHub.

[deppen8]

I investigated this a bit and it doesn't seem like the code in #222 is the full code for generating all the figures in the lesson. Is it possible that code lived elsewhere or got removed in a different PR?

[uschille]

You're right @deppen8. The code directory removed in #222 contained Python scripts for the examples in each episode. Since we encourage using Jupyter notebooks, those scripts are likely no longer needed. I checked out the old code directory but a number of the scripts fail because the directory structure has changed.

I recall that at some point we discussed whether we should include Jupyter notebooks in the repository that could be used with Binder for instance. I think we decided against it because of the risk of divergence between the notebooks and the lesson website. I have notebooks for a few episodes in a separate branch but not for all episodes.

The bottom line is, I am not sure if there was ever a complete set of code to generate all the figures in the lesson. So I might suggest to close this issue and keep the idea of including code as instructor notes in mind moving forward.