Can We use Quarto Yet?

[zkamvar]

As of 2021-09-02, not quite because there is no native support for remote theming in the way we use {varnish}: quarto-dev/quarto-cli#103

Here are my thoughts at the moment (though they may evolve):

The strength of the new lesson infrastructure is the fact that all of our components are clearly separated, which means that it is not infeasable to consider multiple entry points to our lesson

Quarto is a drop-in replacement for RMarkdown for folks who just want to be able to write technical documents and present them without any bells and whistles (though, to be fair, there are a lot of bells and whistles). The problem for us is that we need a little more control of the output so that we can adapt it to our own templates.

[cderv]

If I may chime in, I believe Quarto will probably gain in the future some extension mechanism to create custom output formats (similarly to rmarkdown or bookdown). This could help you when this time come.

Your use case that we already discussed once would be a greate opportunity to do the right thing and add missing feature from R Markdown website that lead you to pkgdown. In my opinion...

[jjallaire]

I'd be surprised if we couldn't get something to work well for your use case even given current constraints. Could you let us know exactly the gaps and we can reason about how to bridge them?

[cderv]

Taking the opportunity to just putting here some notes I have from previous discussion on R Markdown website and this project:

• sandpaper uses pkgdown to create a website for the flexibility it provides regarding templating system. One can create a template package to use which contains default configuration + additional / new template + parameters to configure per project.

• varnish (https://github.com/carpentries/varnish) is the pkgdown template project that is used. It contains html template with placeholder filled by parameters in pkgdown.yml, + some styles specific to the project.

I also believe we could get something to work as Pandoc has all the feature need (templating mechanism) and Quarto brings some nice new features (theming using scss file). I was wondering if everything is there yet... 🤔

Happy to know more about the differences - Project may have evolved since our last talk. 😄

[zkamvar]

Thank you both for being so responsive! I definitely think that Quarto has a future with this infrastructure!

Chris is absolutely correct in how we are currently set up and I absolutely agree that we could set up pandoc templates for this (a la some hybrid between {rticles} and {pkgdown}).

I have more thoughts, but I am currently at the end of my day and out of steam. Be back on Tuesday!

[jjallaire]

Okay, great. Look forward to discussing further. I reviewed your requirements document (https://carpentries.org/blog/2020/08/lesson-template-design/) and am pretty sure you could pretty close to the ideal system you describe w/ Quarto today.

One thing you might not have seen (that addresses the dependencies problem mentioned in the doc) is the ability to freeze computational output (https://quarto.org/docs/projects/code-execution.html#freeze). The idea here would be that individual lessons can have whatever dependencies they need but that doesn't impose installation of those dependencies on anyone that wants to render the site. Consequently, you could have a site that uses R & Python (+ packages for both) but that can actually be rendered with only an installation of Quarto (no R or Python required b/c the computations are cached in the _freeze directory).

[zkamvar]

I have more thoughts, but I am currently at the end of my day and out of steam. Be back on Tuesday!

well, I guess, s/Tue/Wedne/.

In any case, I think we landed on a very similar implementation and I don't think it should be too hard for us to adapt in the future 😁

I really like how you've made it easy to freeze and redirect generated content and I'm really impressed at how easy it was to install. This is key for us because we are really focused on making the process of creating, contributing, and curating lessons straightforward for newcomers.

What I've developed so far is similar in the sense that it defaults to auto-freezing, but it differs because it follows a more {blogdown}-like approach where we cache the markdown files generated via knitr and have a text database recording the source, md5sum, and output (which would be similar to the output of quarto render --debug, I think). Because our lessons are developed by several contributors with their own unique setups (though we are giving the option to use {renv}), these files are not tracked by git locally. Instead, using the {pkgdown} method, they are added to an orphan branch on the remote Git server.

We use these sources to not only re-render websites weekly (to update styling), but also to give maintainers an easier time auditing what would change in a given pull request where packages update because markdown is easily diff-able (for a slightly contrived example, zkamvar/test-with-renv#4 updated a single package, which generated zkamvar/test-with-renv@acd8000).

That all being said, I'll be really glad for the day that I don't have to tell people to install a whole computer language (or four, as we have in our current template) in order to make a lesson on needlepoint.

[zkamvar]

(also, sorry for the long-winded response)

[jjallaire]

Yes, the _freeze dir sounds similar to what you store on the orphan branch. We store the md5sum and the markdown + other file output (and the source isn't tracked separately from what is checked in on the same branch).

Hopefully we can make quarto work well for you next generation of this infrastructure. Once you dig into it pls do let us know wha the gap are and hopefully we can close them.

[zkamvar]

In some initial testing, there are still some quirks that we must overcome in order to use quarto. Namely there is a clash between some of our sections and those provided by quarto:

https://quarto.org/docs/authoring/cross-references.html#theorems-and-proofs

This causes a problem with rendering our documents in quarto because as soon as we attempt to render any document that uses the ::: solution blocks, we get this error:

Error running filter /opt/quarto/share/filters/crossref/crossref.lua:
/opt/quarto/share/filters/crossref/crossref.lua:2009: attempt to get length of a nil value (field 'content')
stack traceback:
	/opt/quarto/share/filters/crossref/crossref.lua:1103: in function </opt/quarto/share/filters/crossref/crossref.lua:1097>

The reason this error happens is because the theorem() filter assumes that this "solution" is a solution to a proof/theorem/mathy thing instead of a dropdown solution in a Carpentries lesson and is trying to format the heading as the solution title and expects an explanatory paragraph so it would be perfectly fine to write something like:

::: solution

### Heading

text text

```
code
```

:::

This would produce a solution block that would look like this

::: {.solution .proof}
[*Heading*. ]{.proof-title}text text

```
code
```
:::

Which, as an aside, is not what we want...

But, because Carpentries lessons often have solutions that are just code examples, we end up with something that looks like this, which causes Line 119 to bork for a reason that I'm not entirely certain.

::: solution

### Heading

```
code
```

:::

[zkamvar]

The solution to #161 (comment) is to add a lua filter to modify solution blocks that acts before quarto filters

quarto-dev/quarto-cli#1854 (comment)

[rbavery]

Hi @zkamvar I noticed this was labeled as nice to have. The workbench docs seems R focused, what's the guidance on converting python notebooks to markdown files that conform to the lesson template? Is this still a manual process?

[zkamvar]

@rbavery,

Thank you for your comment on this. I hope I can clarify. Please respond back if you would like any further clarification.

At the moment, it is still a manual process (as it was in the carpentries/styles). The reason why we haven't yet been able to implement it boils down to strategy for support and deployment. I believe that I've sufficiently modularized The Workbench to allow for this, but we didn't want to make too many changes at once because each new feature brings on the following challenges:

1. Limited capapcity. Quarto was being developed after initial development of The Workbench. They had 10X the resources, so they reached the finish line first, but there are differences in minor rendering processes that need to be worked out on our end before we can integrate it (e.g. you can use the quarto freeze feature for caching, but the rendered files are tracked by Git, which leads to difficulties in how to resolve differences between user and remote machines).
2. User-friendly setup. Quarto is straightforward to set up, but even when we do integrate quarto, it then opens up the question of how you provision the external packages and languages required to build any lesson in both remote and local environments (@milanmft is working on a solution in Add support for setting up Python through renv #448) in a way that matches the features that R users of The Workbench enjoy so that working on The Workbench does not clobber any global libraries, modify the environment, or depend on The Workbench to work when taken out of context.

For more context, you can view this rejected proposal for funding from the R Consortium that we wrote last year: https://zkamvar.github.io/isc-proposal-workbench-2022/

[rbavery]

Thanks for the detail @zkamvar and all your thought and work on this. I'm excited for #448 and for this to be integrated in the workbench so that there's less overhead to developing python lessons.

[rbavery]

Just adding a note that

it then opens up the question of how you provision the external packages and languages required to build any lesson in both remote and local environments

seems like a job for a cross-platform package manager like conda/mamba

https://github.com/mamba-org/mamba
https://mari-meir.medium.com/rhumba-a-faster-r-distribution-d619fb93043a

[milanmlft]

Regarding the discussion about notebook conversion, this might also be relevant: #42 (comment)

[bbartholdy]

I just wanted to note that I would love to see this (Quarto support) implemented! I'm a huge fan of Quarto and it offers so much more than R Markdown from which I think the workshop attendees (R for Social Scientists) would greatly benefit. It's even to the point where I end up recommending Quarto after the R Markdown episode.

In the meantime, maybe someone can offer insights on the best way to incorporate a temporary Quarto episode for our workshop? My current solution is to have the Quarto episode as a .qmd file with keep-md: true, and then render manually. sandbox::serve() picks up the Quarto .md output and renders that. The only downside is the manual rendering and the loss of Quarto features (such as crossrefs and shortcodes) as the md episode is built for the lesson.

[milanmlft]

Already mentioned in the Carpentries Slack, but reposting here for visibility:

I've been experimenting with creating a Quarto extension for the workbench: https://github.com/milanmlft/carpentries-quarto
It's still very early stage and I have only limited capacity to work on this, but I'd be happy to get any feedback and/or contributions 🙂
I think the long-term goal would be to use this as an alternative to varnish and then let sandpaper render episodes through the R Interface to Quarto using the Carpentries extension to handle styling and layout. But that's just my current (vague) idea.

[milanmlft]

Looks like pkgdown 2.1.0 is going to support Quarto (currently already in devel)! This might make things much easier, as sandpaper is built around pkgdown. Haven't looked at it in detail yet, but it seems promising.

See also r-lib/pkgdown#2656