Import lesson template's scripts for format checking and rendering

[eldobbins]

The Carpentries Lesson Template includes a section on Checking and Previewing. There are scripts for that which are not included in the python-aos-lesson.

I would like to try using those scripts to render locally before I push changes to my repo. But it might not be needed if most development and editing is done directly in GitHub. If I use the scripts, I will PR a branch with them.

[eldobbins]

Once again, this is much more complicated than I expected. I was planning to use the Carpentries Lesson template as the basis for the changes. However, that lesson uses "The Carpentries style version 9.5.3." whereas AOS says "Using The Carpentries theme". These seem to have very different structures.

[DamienIrving]

Thanks for spotting this, @eldobbins.

@fmichonneau - What is the relationship between the following two sites?
https://github.com/carpentries/styles
https://github.com/carpentries/carpentries-theme

Do we need to update this repo (perhaps by starting all over following the instructions at https://carpentries.github.io/lesson-example/ ?) in order to get the benefit of updates and improvements to the carpentries lesson style?

[fmichonneau]

Hello both,

Yes, lessons in the Carpentries Incubator, the CarpentriesLab, and some of the more recent official lessons use the remote theme feature from GitHub.

For these repositories, to preview the lessons locally, you need:

• ruby
• bundler

We have had a pull request open for a while that provides instructions for installing those. It hasn't been merged because of a lack of testing on Windows (and in general, we'd welcome more feedback on the instructions).

So, depending on your setup, you might be able to run:

make serve

as all the other lessons and get the lesson rendered locally. If not, use the installation instructions included in the pull request to install ruby and bundler.

Please feel free to reach out here if there are any questions I might be able to answer. Thanks!

[eldobbins]

@fmichonneau Thank you for your reply. I read the PR and carpentries/maintainer-RFCs#1. But I'm still a little confused.

Is https://carpentries.github.io/lesson-example/index.html the best example of how to set-up a lesson currently? I do not see a reference to remote themes in that lesson. Is there a different template for a lesson with remote themes?

Are remote themes definitely the way lessons will be organized in the future? Is there a method for migrating lessons from an older format to the new one? I'm concerned that we might put time into migrating to a new format that will be out-of-date in a little while.

Or is this lesson, perhaps, already up-to-date because it is in CarpentriesLab? Then I just need to use the newer rendering solution.

[fmichonneau]

Are remote themes definitely the way lessons will be organized in the future?

Yes, we are currently still in a testing phase to understand pain points for lesson contributors and maintainers.

Because we are in a testing phase and some details may change, we are working on the documentation aspect. Typically, I have worked closely with people who have been using our remote themes so I apologize for the frustration of trying to figure things on your own with no documentation.

Other aspects that need improvement are:

• re-organization of the styles repository to continue to provide updates for files that are not included in the remote theme
• documentation on how to transition to using the remote theme
• modifications of the scripts that check the formatting of the lessons (the lesson_check.py script for instance). Help with this would be greatly appreciated!

In this testing phase, I'm happy to provide the support needed to ensure that your lesson will be functional and will use this information to shape the documentation. If you are working in a different repository and need help to get set up, please let me know. My email is [email protected].

[eldobbins]

I ended up using Anaconda to install Jekyll et al. I'm on a Mac, and thought originally I could use the default ruby install. But that turned out to be for system stuff and required constantly sudoing. I tried compiling Jekyll myself, but couldn't get eventmachine to compile. Luckily, there is a version of Jekyll on condo-forge.

I'm submitting a PR that includes the YAML file for the conda environment, and the bare-bones additions needed for make lesson-check to at least get started. It isn't running all the way through, but I think that will be a series of future PRs to fix.

[eldobbins]

https://github.com/carpentrieslab/python-aos-lesson/pull/30