R: loose ends in the vignette workflow

[jennybc]

I've just enjoyed the new runtime support for .Rmd files (#1043), in the context of working on package vignettes.

One thing I did was to click "Preview" and I notice a few things about the state that leaves Positron in:

1. Lots of files are left behind in vignettes/VIGNETTE-TITLE_files/. I suppose this could just be something to resolve with gitignore. But it feels like RStudio must take my stuff to some more behind-the-scenes location before render?
2. The (a?) terminal is now tied up and actively watching the file for changes. I didn't expect this.

[jennybc]

Related to or maybe just part of #1421

[juliasilge]

I have accidentally hit "Preview" on a NEWS file in Positron and it made just a ton of files I had to manually clean up afterward.

In RStudio, looks like "Preview" makes the HTML in my temp directory, which I much prefer:

The "Preview" button in Positron comes from the Quarto extension, right? What are some options for changing what this does?

[jennybc]

Everything described here continues to happen (file explosion and terminal occupied with file watching).

[hadley]

Similarly problem with hugodown blog posts, with the additional problem that quarto generates a .html file instead of a .md.

[juliasilge]

This came up in private beta here (specifically about README preview going to the working directory): https://github.com/posit-dev/positron-beta/discussions/130

[juliasilge]

Started work on this in quarto-dev/quarto#435

[juliasilge]

Let me update where we are on this:

Quarto uses the terminal

Quarto using a terminal to serve a preview is as designed and we don't have a straightforward way to run it somewhere secretly in the background. It is quite straightforward to open a new terminal so I don't think this is a big usability problem (instead, a difference for folks to get used to):

Quarto puts a bunch of files where it renders

We are in the process of fixing where the contents of "Quarto: Preview" go when you are in an R package, in quarto-dev/quarto#435 plus some work that @cscheid is doing in Quarto itself. The outcome here will be that the HTML and other files will go to a temp directory and will not show up in the R package directory.

What about hugodown?

For hugodown @hadley, the big challenge is output: hugodown::hugo_document. We're not going to be able to support all rmarkdown formats, especially ones defined in other R packages. I think if you want to update hugodown but keep using rmarkdown, you would change this advice:

To knit an .Rmd post, you can use the Knit button to knit to the correct output format. You can also use the keyboard shortcut Cmd+Shift+K (Mac) or Ctrl+Shift+K (Windows/Linux).

To instead say:

To knit an .Rmd post, you can use rmarkdown::render() to knit to the correct output format.

Alternatively, you can update the package to use Quarto explicitly, with .qmd and format: hugo-md. Then you can use either the Preview button/shortcut, the command line, or the command palette (use "Quarto: Render Document") to generate the markdown.

[cscheid]

Just to add a bit more wrt output: hugodown::hugo_document. A similar problem happens with Quarto and (say) output: html_document. We just happen to "get lucky" because the default output for Quarto is html. @cderv and I have discussed adding functions to the quarto R package that would convert metadata from Rmd-speak to qmd-speak.

We expect that these helper functions would catch a large fraction of common use cases, so that specific pain point would be alleviated substantially.

[juliasilge]

Just for clarity, this particular output isn't part of rmarkdown itself but an extension in a separate R package, like this; I would expect these to be lower priority for conversion than what it is in rmarkdown itself.

[hadley]

To be clear, all I want for hugodown is for Cmd + Shift + K to run rmarkdown::render(); that saves me having to type it by hand in the console.

[cscheid]

@hadley I might be missing something, but does rmarkdown::render() automatically produce a preview in RStudio? I think part of the problem is that the Quarto extension provides previews (Cmd + Shift +K) through quarto preview, which necessarily won't go through rmarkdown::render().

[hadley]

@cscheid yeah, I mean run rmarkdown::render() and then show me the results 😄

[juliasilge]

I'm going to add detail to #1421 to explore options for that @hadley.

Let's make this issue "R package development .Rmd needs, so Positron is a viable IDE to use for R package development".

For QA and confirming that we have the behavior as expected now, one will need to:

• Install at least the 1.5.34 Quarto prelease
• Install the .vsix for the Quarto extension generated via GH Action artifact, like the one on this page (download the artifact, unzip, install in Positron via "Extensions: Install from VSIX...")

Then you will be set up to check behavior:

In an R package workspace

• Click "Preview" on an .md file like NEWS.md; you will see the preview in the Viewer pane and there will be no HTML or other files generated in the R package directory
• Click "Preview" on an .Rmd like README.Rmd or a vignette; you will see the preview in the Viewer pane and again there will be no HTML or other files generated in your working directory

In a workspace that is not an R package

• Click "Preview" on an .Rmd file; you will see the preview in the Viewer pane and there will be generated HTML and other files created in your working directory.

[jennybc]

Current versions of Positron and quarto and the quarto extension:

Positron Version: 2024.05.0 (Universal) build 1283
Code - OSS Version: 1.89.0
Commit: 2011f97
Date: 2024-05-22T03:43:44.024Z
Electron: 28.2.8
Chromium: 120.0.6099.291
Node.js: 18.18.2
V8: 12.0.267.19-electron.0
OS: Darwin arm64 22.6.0

~/rrr/devhelp % quarto --version
1.5.37

✅ In an R package, if I click the "Preview" button, an html preview of the NEWS file appears in the Viewer and no related files are left behind in the source package. Ditto for a vignette. (The change made to .gitignore seems a bit wonky; I will open an issue on quarto-cli for that. Also for the fact that a related entry should be added to .Rbuildignore if it's not already there.)

✅ In a folder that is not an R package, if I click the "Preview" button for an .Rmd file, it appears in the Viewer. The .html file and the whatever_files/ directory are left behind in the folder.