Output rendered file path information as output for `quarto_render` (or something else than `NULL`)

[llrs-roche]

There is no information about the output of quarto_render.
Could it be made informative? Such as the name of the output files or the success of the quarto CLI process?

Thanks

[cderv]

You mean a returned value instead of none ?

quarto-r/R/render.R

Lines 193 to 194 in ec42247

	# no return value
	invisible(NULL)

Otherwise there should be the usual CLI logging

> quarto_render("README.md")
pandoc 
  to: html
  output-file: README.html
  standalone: true
  section-divs: true
  html-math-method: mathjax
  wrap: none
  default-image-extension: png
  
metadata
  document-css: false
  link-citations: true
  date-format: long
  lang: en
  
Output created: README.html

[llrs-roche]

I'd like it to be documented that quarto_render returns NULL invisible. On the current documentation there is no mention to the quarto_render output at all, it goes from describing input to the examples:

If possible I'd like to get quarto output (success or failure at least). This can be helpful to improve error handling when rendering documents or projects within R.

[cderv]

On the current documentation there is no mention to the quarto_render output at all, it goes from describing input to the examples

Sure I can add a result part. I should have. Sorry for that.

If possible I'd like to get quarto output (success or failure at least). This can be helpful to improve error handling when rendering documents or projects within R.

If there is a failure, then an error should be thrown. So no result.

Either quarto CLI error is rethrown

> quarto::quarto_render("does-not-exist.qmd")
ERROR: No valid input files passed to render

Or error is thrown in R directly when quiet = TRUE

> quarto::quarto_render("does-not-exist.qmd", quiet = TRUE)
Error in `quarto::quarto_render()`:
✖ Error running quarto cli.
ℹ Rerun with `quiet = FALSE` to see the full error message.
Caused by error:
! System command 'quarto.exe' failed
Hide Traceback
    ▆
 1. └─quarto::quarto_render("does-not-exist.qmd", quiet = TRUE)
 2.   └─quarto:::quarto_run(args, echo = TRUE, quarto_bin = quarto_bin)
 3.     └─base::tryCatch(...)
 4.       └─base (local) tryCatchList(expr, classes, parentenv, handlers)
 5.         └─base (local) tryCatchOne(expr, names, parentenv, handlers[[1L]])
 6.           └─value[[3L]](cond)
 7.             └─cli::cli_abort(msg, call = .call, parent = e)
 8.               └─rlang::abort(...)

What would you expect as sucess or failure in output ?

I am really not sure how to modify / improve the current situation I created. So please, if you have a suggestion in mind, do tell me precisely what you are expecting.

This will help me deeply to understand what is not working well in the way you are using quarto::quarto_render()

Thank you !

[llrs-roche]

I'm fine with rethrowing an error although I thought that perhaps a logical value describing the outcome could be informative, this is the output of file.* functions on base R (and it is recommended to check the output):

rendering <- quarto::quarto_render("does-exist.qmd")
if (rendering){ 
   moving <- file.rename("does-exist.html", "path/does-exists.html")
   if (!moving) {
      stop("File not possible to move")
} else {
  stop("Rendering failed")
}

Why I need to check the output, because I want to use the file name to move the file or simply display a log message, For this reason quarto_render could directly return the name/path of the files created. Currently the user is left to guess/store the name of the file and operate with it independently from the function that generates. I have to do something like:

document <- "document.qmd"
lf <- list.files(full.names = TRUE)
quarto::quarto_render(document)
lf_new <- list.files(full.names = TRUE)
output_quarto <- setdiff(lf_new, lf)

Note that if the same document is rendered, I have to check the dates before and after to know that quarto modified a file.
If I know what is the output format of quarto_render I might do something like this:

document <- "document.qmd"
out_document <- tools::path_sans_ext(document)
quarto::quarto_render(document)
lf_new <- list.files(full.names = TRUE)
output_quarto <- lf_new[startsWith(lf_new, out_document)]

I hope these examples are clear of how I'm using quarto::quarto_render(), why, and how it's output could help me as a user/developer. Thanks for the quick answer!

[kwbyron-lilly]

I would suggest returning the file path invisibly like rmarkdown does. This is useful for troubleshooting at the least. I'm working on getting a shiny app to generate reports in quarto. knowing where that file is being created would have saved me a bit of sleuthing.

[cderv]

Why I need to check the output, because I want to use the file name to move the file or simply display a log message, For this reason quarto_render could directly return the name/path of the files created. Currently the user is left to guess/store the name of the file and operate with it independently from the function that generates.
(...)
I would suggest returning the file path invisibly like rmarkdown does.

@kwbyron-lilly @llrs-roche It is easy with rmarkdown because calling rmarkdown::render() returns a R object. Here calling quarto render is done using subprocess (with processx) and so it would require parsing the standard output. Not sure it is safer long term.

I could also always set -o so that I compute the output in R and can return it, but this would mean always overriding the default.

All this seemed too much to do by default in this package, also because output path is output in log. (which really push do the user who need it the responsability to catch and parse the stdout).

I can revisit though if we find a way to do that cleanly and safely on the long term.

This is useful for troubleshooting at the least.

Output path should be printed as stdout when quiet = FALSE, so I figured this was enough for troubleshoot... 🤔

Currently the user is left to guess/store the name of the file and operate with it independently from the function that generates.
(...)
I'm working on getting a shiny app to generate reports in quarto. knowing where that file is being created would have saved me a bit of sleuthing.

In those type of usages, where you embed the quarto_render() call for the user, wouldn't that be safe for your to control output_file name so that you know where the document is located and then moving it ?

I understand how that can be useful. Again, quarto runs in a background process to retrieving the output path computed by Quarto is as "difficult" from quarto R 📦 as it would be for your in your shiny app. (not sure if this is clear - I mean quarto render is third party called through processx::run()).

Currently, we are in R Scripting with quarto_render in the same situation as if you were scripting with bash and calling quarto render. This won't output the different output folder and path, except on standard output.

So one thing I could do is returning the processx::run() output directly, so that it can be accessed by user (instead of capturing output... 🤔)

Currently capturing output is required

> res <- capture.output(quarto::quarto_render("index.qmd"))
> output_log <- res[grepl("Output created: (.*)", res)]
> output_file <- stringr::str_match_all(output_log, "Output created: (.*)")[[1]][,2]
> output_file
[1] "index.html"

One thing that could be leverage is quarto inspect available through quarto_inspect(), but I don't think we compute yet output paths. This is something that would really be possible if the following is tackled

• Epic: Execution Planner quarto-cli#6518

stop("Rendering failed")

About this @llrs-roche, currently if rendering fails, then quarto_render() will throw an error always (unless I missed some case and please to share an exception).

This means you code will stop at the error anyway, and if you want to failed differently than usual tryCatch or other condition handler needs to be used.

I hope these examples are clear of how I'm using quarto::quarto_render(), why, and how it's output could help me as a user/developer. Thanks for the quick answer!

Yes definitely useful !

I am open to suggestion and PR, so please to share your ideas !

[llrs-roche]

Why I need to check the output, because I want to use the file name to move the file or simply display a log message, For this reason quarto_render could directly return the name/path of the files created. Currently the user is left to guess/store the name of the file and operate with it independently from the function that generates.
(...)
I would suggest returning the file path invisibly like rmarkdown does.

@kwbyron-lilly @llrs-roche It is easy with rmarkdown because calling rmarkdown::render() returns a R object. Here calling quarto render is done using subprocess (with processx) and so it would require parsing the standard output. Not sure it is safer long term.

I understand how {quarto} works, my petition is to make it easier to work within R. If it is not safe, to capture the output which is the safe option for the user?

I could also always set -o so that I compute the output in R and can return it, but this would mean always overriding the default.

This solution doesn't work well if a document is rendered in multiple formats:

---
title: "Validation Report"
date-format: "ddd MMM DD hh:mm:ss A YYYY"
format:
  html: 
    toc: true  
    embed-resources: true
  gfm:
    html-math-method: webtex    
  typst:
    toc: true
    section-numbering: 1.1.1
    df-print: default
    margin:
      x: 2cm
      y: 2cm
---

The path from html to the gfm is absolute or to the same folder AFAIK.

All this seemed too much to do by default in this package, also because output path is output in log. (which really push do the user who need it the responsability to catch and parse the stdout).

I can revisit though if we find a way to do that cleanly and safely on the long term.

This is useful for troubleshooting at the least.

Output path should be printed as stdout when quiet = FALSE, so I figured this was enough for troubleshoot... 🤔

Currently the user is left to guess/store the name of the file and operate with it independently from the function that generates.
(...)
I'm working on getting a shiny app to generate reports in quarto. knowing where that file is being created would have saved me a bit of sleuthing.

In those type of usages, where you embed the quarto_render() call for the user, wouldn't that be safe for your to control output_file name so that you know where the document is located and then moving it ?

If the file rendered is rendered to multiple formats it is not as easy, as shown above. Also considering that some files might be silently replaced.

I understand how that can be useful. Again, quarto runs in a background process to retrieving the output path computed by Quarto is as "difficult" from quarto R 📦 as it would be for your in your shiny app. (not sure if this is clear - I mean quarto render is third party called through processx::run()).

Currently, we are in R Scripting with quarto_render in the same situation as if you were scripting with bash and calling quarto render. This won't output the different output folder and path, except on standard output.

So one thing I could do is returning the processx::run() output directly, so that it can be accessed by user (instead of capturing output... 🤔)

This could work at least for the moment, if the quarto CLI output doesn't change too much.

Currently capturing output is required
One thing that could be leverage is quarto inspect available through quarto_inspect(), but I don't think we compute yet output paths. This is something that would really be possible if the following is tackled

• Epic: Execution Planner quarto-cli#6518

Yes, it doesn't seem it would help at the moment. Maybe when issue quarto-dev/quarto-cli#6518 is resolved inspect might help.

stop("Rendering failed")

About this @llrs-roche, currently if rendering fails, then quarto_render() will throw an error always (unless I missed some case and please to share an exception).

This means you code will stop at the error anyway, and if you want to failed differently than usual tryCatch or other condition handler needs to be used.

Ok, I'll use tryCatch.

[cderv]

I think what you are seeing while using quarto_render() is the same observation as if you would try to wrap quarto render directly.

I guess my feeling that I don't want to try provide a R 📦 only solution to this. It is not currently easy to get the output right as you explain, and this is because the information is internal to Quarto CLI and not exposed.

Probably what is needed is really #quarto-dev/quarto-cli#6518 as all output paths will be needed and can be exposed to third party tooling.

Until then, we only rely on workaround based on expectation from quarto CLI behavior, or what is reported by Quarto itself.

Something to try currently would be to work with Quarto Project, and leverage post render script where some environment variables are set regarding outputs

• https://quarto.org/docs/projects/scripts.html#pre-and-post-render

Maybe this is a starting point to improve how quarto can communicate information after the rendering to external process.

I think this is next thing to do - improve quarto CLI and then adapt the R package;

[llrs-roche]

Not all that use quarto use projects. Projects doesn't work well when providing a quarto parametrized report from a package.
I hope quarto-dev/quarto-cli#6518 will be added soon, until then I might switch to rmarkdown. Due to this an other limitations (I hoped to use brand.yaml but it seems it can only be used for projects not standalone documents).
Thanks for all the feedback, looking forward for future developments on quarto

[cderv]

Not all that use quarto use projects

I know that :) I was trying to thing of current workaround and what works - and maybe what could be extended to single document rendering;

Projects doesn't work well when providing a quarto parametrized report from a package.

I'll be interested by knowing more on this in another issue. Project of type: default are supposed to be a way to activate project related features, while being very similar to rendering each doc on their own. So parametrized report should work even when the file is part of a default type project.

I hope quarto-dev/quarto-cli#6518 will be added soon,

quarto-dev/quarto-cli#6518 is huge work. There is a lot of component evolved to be able to make a complete execution map of all the input files, their resources and their output, and how each of them impact others. So not ETA on that. We know we want to do it.

until then I might switch to rmarkdown.

This is unfortunate. Please send me link by email a full project that you have with R Markdown and that you are blocked to move to Quarto and benefit from new feature because of this problem.

Though I understand that to wrap rendering into R tooling only, rmarkdown has more interest, because it is coded in R completely. So if you have everything you need with rmarkdown - no need to switch for sure. If you want to benefit some new feature from Quarto, but you can't because of this problem - then this is something I consider bad design from my side.

I'll keep thinking at what I could do to improve, but if you can send me real case usage - this would definitely help me understand the problem faced and find good solution.

Due to this an other limitations (I hoped to use brand.yaml but it seems it can only be used for projects not standalone documents).

Brand feature should work without Project too. I did a quick test, and it seems to be working well for me. If you find it otherwise, please open a discussion or issue in quarto CLI.

Though again, I would encourage to still look at project, which brings nice feature. I am also interesting to understand better in which of your use case project does not work well for you. I'll be happy to know more - you can contact me by email, and we can even schedule a call to share live.

You have valuable feedback that really helps us - thank you !

[cderv]

After more thoughts, I am not confortable parsing the verbose output when quiet = FALSE to get the output.

Too more variant

• output_file set or not ?
• what to do when quiet = TRUE ?
• Unthought use case ?

I think this will be way better to be able to compute from inspect when this is done:

• inspect - show output-file path quarto-cli#12805