styles
styles copied to clipboard
carpentries
clearly style supplementary episodes
Hello,
Currently, the r-novice-inflammation lesson lacks a clear delineation of supplementary episodes. I noticed which episodes are supplementary because of the rmd names, but at first glance, the episode order looks somewhat nonsensical. On this page, the supplemental episodes are 9-15.
I am aware that this is a rather large ask, but I would strongly prefer a template that allowed us to "sandbox" the supplementary episodes on that page.
This would also close issues swcarpentry/r-novice-inflammation#220 (it's almost two years old!) and swcarpentry/r-novice-inflammation#284 (it comes up annually, apparently).
Hi @diyadas. This issue looks more appropriate for swcarpentry/r-novice-inflammation repository unless something is required from this (styles) repo.
Argh I meant to create this in swcarpentry/lesson-example, oops. Got confused because the help for this repo points to that page. 🤦♀️
Actually, I just realized that this may be the domain of the styles repo, as I'd like to modify _includes/syllabus.html. Basically, the issue with the syllabus is that the supplementary episodes are listed in the table after the main episodes, and they do not at all follow chronologically. Some of the supplementary episodes are meant to be taught well before some of the main episodes, should the instructor choose. For example, the first episode in the workshop we are teaching next week is actually going to be episode 9, and not episode 1. Obviously, this numbering is very confusing.
I'd like to have a separate table with the supplementary episodes on the syllabus page, dropping the numbering, adding columns for episode length and possibly suggested placement in the lesson.
One way to accomplish this is would be to have a episode.type variable defined for supplementary episodes, i.e. episode.type: supplementary in the episode header and then use on the syllabus page {% if episode.type != "supplementary" %}, {% if episode.type == "supplementary" %}, and in that way choosing the content to go into each table, etc.
Alternatively, if you think no other lesson uses supplementary episodes, I'm happy to make the changes to r-novice-inflammation (with @katrinleinweber 's agreement) but since it involves modifying an include, I'm wary of diverging from the overall styles repo.
@diyadas Thanks for the issue. I agree that make clear for learners and instructors which episodes are important and which ones are supplementary will be great. I think that have a _supplementary folder similar to https://github.com/swcarpentry/lesson-example/tree/gh-pages/_extras would be better that add extra metadata. Said that, I want to wait a little bit to make such change.
I don't see any problems using either metadata approach or by placing episodes in _supplementary folder. However, the latter approach would require a clarification about the difference between _supplementary and _extras (even though it seems to be straightforward).
@rgaiacs, can you invite other maintainers to this thread?
Having a _supplementary folder might mean that we'd also need a _supplementary_rmd folder...
I'm wondering if it would be better to identify supplementary lessons using a prefix in the file name, and rely on the Make script to move the rendered version to the _supplementary folder? This would ensure that all the episodes are in the same place.
+1 to @fmichonneau's idea. Seems simplest. This is also an issue we formed a committee (the 'pathways' committee) to talk about this past Spring. r-novice-gapminder also has a ton of episodes and not all are ever taught. The issue is that depending on the interest of the workshop, you can take different paths through them, and so there is no clear 'supplemental' set and 'canonical' set. Perhaps this is a different problem than r-novice-inflammation?
I'm wondering if it would be better to identify supplementary lessons using a prefix in the file name, and rely on the Make script to move the rendered version to the
_supplementaryfolder?
This would not work because GitHub Pages doesn't run our Makefile which would mean that all lessons would need to have their HTML files converted locally. Not have to keep convert Markdown to HTML locally was the main reason that we stopped using Pandoc. My experience with Travis in the last 4 weeks showed me that to have it running our Makefile users will have to do extra steps which is annoying. If people decide to migrate to GitLab and GitLab Pages that can run our Makefile without problem and without extra steps for our uses I'm very happy to adopt this suggestion.
I'll leave the specifics of how the styling of supplementary episodes is managed to those who know how the site builds. Thanks very much for the quick responses.
To address @naupaka 's point, I think the issue we have with r-novice-inflammation is certainly related, but I think there's a clearer order, with the option of inserting/replacing some episodes with supplementary episodes. You could teach episodes 1-8 in that order, but instructors may want to add in some supplementary episodes (9-15).
How about we first try whether a purely visual distinction helps. Can we regex the current -supp- part of the filename in the template code in order to generate a separate table in _includes/syllabus.html and a 2nd episodes section in /navbar.html (AIO would then be the 3rd section in the dropdown).
@rgaiacs When you say "users will have to do extra steps [to enable Travis]", are you referring to enabling the repository from the Travis website? If so, it's something that I could do across our repositories.
I think @katrinleinweber's idea is a good solution to test. We'll need to make sure the regex we use in the Makefile to detect which files get processed by knitr to be converted from Rmd to md can accommodate the -supp- in the file name, but it shouldn't be a problem.
How about we first try whether a purely visual distinction helps. Can we regex the current -supp- part of the filename in the template code in order to generate a separate table in _includes/syllabus.html and a 2nd episodes section in /navbar.html (AIO would then be the 3rd section in the dropdown).
This sounds OK.
We'll need to make sure the regex we use in the Makefile to detect which files get processed by knitr to be converted from Rmd to md can accommodate the -supp- in the file name, but it shouldn't be a problem.
You don't need to do any change to the Makefile.
When you say "users will have to do extra steps [to enable Travis]", are you referring to enabling the repository from the Travis website?
Not only that. If Travis is going to build the lesson and push it back to GitHub they need to add some SSH key.
There is a good R package that works with the Travis and GitHub APIs that flips the Travis switch on, and upload the SSH keys automatically. I'll work on a plan for this once all the repositories have the latest version of the styles repository that includes the .travis.yml file.
You don't need to do any change to the
Makefile.
I'm agnostic about where the occurs in the end, but I did mean "only" the template code, see PR suggestion above. I'm fine with testing it there and then upstreaming a successful solution.