How is the project actually built?

[GentleInfant]

I see on https://carpentries.github.io/lesson-example/index.html that new infrastructure is coming.

However

• on the git page itself it says to use make even though no Makefile is present, so of course that doesn't go far.
• I looked at some other projects and the make calls seem to just be pass throughs to jekyll but running jekyll serve gives me an incomplete looking page

What am I missing?

[gcapes]

This is now done using R I'm afraid - the lessons were built using jekyll before the new infrastructure. Once you've got R installed and the required packages it works rather well (FWIW the setup took me about 1.5 hours as a non-R user)

Instructions I followed are given here:
https://carpentries.github.io/workbench/

I think we should have this question and answer as a 'sticky' somewhere because lots of people will need to know the answer.

Perhaps once we've fixed the link to CONTRIBUTING.md, that file can link to the above setup info? @zkamvar #1297

[bkmgit]

#1387

[zkamvar]

FWIW the setup took me about 1.5 hours as a non-R user

I'm sorry for the lengthy installation time 😦. If you have time (ironic ask, given the circumstance), @gcapes, I would be interested to hear more about your experience with this. I've tested this installation workflow with non-R users (with both linux and non-linux users), but not everyone's setup is the same.

[gcapes]

I was missing a library (can't remember which) and it took a little while to figure out what the required Linux package was called before I could retry the R install/compile. It then took a while to figure out where the html files were for the local build.

[zkamvar]

I take it you are not on Ubuntu, then. What OS do you run? Do the list of system requirements from the API (as described in https://carpentries.github.io/sandpaper-docs/#dependencies-of-dependencies) not help?

[tobyhodges]

It then took a while to figure out where the html files were for the local build.

For anyone else who is working through this process and may be wondering the same thing, the location of the locally-built HTML files is described in the Lesson Deployment section of the infrastructure documentation: you should find them in site/docs/.

It can be confusing at first glance, because the contents of the site folder are ignored by Git: running git status after building the site will not show you a long list of new HTML files as you might expect. (Certainly this caught me by surprise the first time.)

[GentleInfant]

Sorry, ended up a bit side tracked. I haven't had a chance to try the new instructions. Was curious if there was records on why R was selected for this though? It's not an obvious choice to me for webpage authoring...

[zkamvar]

Sorry, ended up a bit side tracked. I haven't had a chance to try the new instructions. Was curious if there was records on why R was selected for this though? It's not an obvious choice to me for webpage authoring...

Most tools for webpage authoring outside of Wordpress and the like expect authors to have some knowledge or ability to manipulate HTML, CSS, JavaScript and one (or two) other languages to wrangle them all together. It's great for people who are dabbling in webpage development, but as we've seen for several years now, it's not great for people who do not have much experience with these technologies (think about the last time you assisted someone to install Jekyll correctly).

We chose R for three main reasons:

1. It has a really robust publishing ecosystem
2. It is available as a binary application on all major platforms with a packaging system that more often than not just works
3. Most of all: The R community as a whole is vibrant, diverse, welcoming, and is most aligned with The Carpentries core values

We teseted this in 2021 to make sure that it works for people with varying levels of familiarity with R: https://carpentries.org/blog/2021/07/infrastructure-testing/

I also have given two talks about The Workbench that go into a little bit more detail about why we chose R (which highlight the points above)

Use!R 2021: https://zkamvar.netlify.app/talk/carpentries-user-2021/ (overview) https://zkamvar.github.io/user2021/#p1 (slide deck with notes)
RStudio conf 2022: https://zkamvar.netlify.app/talk/carpentries-rstudio-2022/ (overview) https://zkamvar.github.io/rstudio-conf-2022/#p1 (slide deck with notes)

I hope that helps with understanding the rationale and I would be happy to clarify anything further.

[deppen8]

@zkamvar beat me to it while I was looking for the links. 😁 Thanks, Zhian!

[zkamvar]

The links I create are like spiderwebs in the forest during an afternoon hike: they don't really hit you in the face.

This response is now in the FAQ: https://carpentries.github.io/workbench/faq.html#why-r

[GentleInfant]

Thanks for all the comments and replies. I've get it up and running now. I have one more question while I have some people's attention then I'll close the ticket. I have a few other things about courses where I'm like 'this was almost certainly a deliberate decision and I'd like to know why', how would I best go around finding the why. Doing it in github comments doesn't feel appropriate but a lot of the channels in Slack seem not super active. Is there a wiki or something where decisions are documented/discussed?

[tobyhodges]

@GentleInfant some lesson sites contain information about decisions made in the design process, in the Instructor Notes page - the page for Programming with Python is a good example of this.

But it has only been done rarely and inconsistently from lesson to lesson, and is certainly something we could be better at as a community IMO. I hope to integrate a "Lesson Design Notes" page into the lesson infrastructure, where this kind of information could be recorded.

Generally speaking, if something doesn't seem right to you, or you have improvements to suggest in the lessons, I really do encourage you to open an issue on the relevant repositories, just as you did here. You probably are not alone and, although coordinating community effort around lesson updates is hard and progress is sometimes slow, I am sure your questions and the answers they receive will be helpful to others.

Anyway, while I hope that - in some cases, at least! - the things you are asking about will have been the result of deliberate decisions, I am sure that won't always be the case. Decisions made in the past should also be subject to review too*, so there really is no harm in asking!

* the discussion of adopting git switch and git restore in the Version Control with Git lesson is a great example of how the circumstances around a design decision can change.

[GentleInfant]

Thanks for your replies everyone. More annoying questions incoming ;)