Integrate chosen flow diagram to help page

[moodymudskipper]

The use case I have in mind is to use flow_view_deps() for internal documentation purposes but let's aim for more flexibility.

We can insert a flow diagram using this template in the roxygen2 doc :

#' \if{html}{\figure{`r basename(flow::flow_view_deps(some_function, out = "man/figures/foo.png"))`}{options: width="40\%" alt="my alt text"}}

Though, as all images I think, it won't show it with devtools, we need to actually install, restarts, call library then view the file.

This is a bit long though, maybe we can provide a tool to make it simpler ?

[moodymudskipper]

This seems to work quite well, a bit hacky but whatever:

flow_embed <- function(call, name, width = 1, alt = name) {
  name <- paste0(name, ".png")
  path <- file.path("man/figures", name)
  if (!file.exists(path)) {
    call$out <- path
    eval.parent(call)
  }
  call <- substitute(call)
  sprintf(
    '\\if{html}{\\figure{%s}{options: width="%s\\%%" alt="%s"}}',
    name,
    width*100,
    alt
  )
}

Then in the doc we only need (for instance):

#' `r flow::flow_embed(flow::flow_view_deps(my_function), name = "my_figure", width = .7, alt = "my alt text)`

Doc should explain :

• flow should be added to Suggests to pass CRAN checks
• namespaced notation is optional if functions are imported but this is unlikely to be a good idea
• the out parameter of flow functions is ignored
• It takes time to create figures so they are not overwritten whenever we document(), to refresh them delete from "man/figures" first (incidentally it also makes it more stable because different systems might create different diagrams)
• We don't monitor the clutter, if you create pngs and don't use them (remove references from doc) you should remove them manually from "man/figures"
• The images might not appear in the doc in dev mode (using devtools), install, restart, attach, query the doc, and it should be fine

[moodymudskipper]

Actually a custom oxygen tag might be better. The user will need an "'@importFrom flow ..." for oxygen methods and then ww'd insert the chart using a syntax like :

#' @flow_view_deps my_function alt="my alt text" width=.7

rn I think it's better to have a different tag for every relevant function, but having "#' @flow view_deps or something similar is possible too. I am not sure if RStudio's autocomplete for tags picks on custom tags but anyway it doesn't provide a description.

No need to worry about figure names, nor how to remove the clutter. Except I need to understand how to remove it through roxygen.

Either oxygen provides a way to make a last pass and remove stuff after the doc is made (I don't think it does), or we need for every tag to :

• initiate a db if not already initiated
• remove every figure that is not referenced in the db
• create figure and reference it in the db

I've never seen named parameters in roygen tags but this seems acceptable, we'd provide decent defaults so they're rarely needed anyway. Or we still provide flow_embed() for cases that require customisation. Or we give parameters positionally starting with width, and NA means keep default.

Where do we document this ? If we keep flow_embed we can keep it there, but it it's obsolete we might only document it in a vignette since we'll have no related exported function.

[moodymudskipper]

Let's go with

#' @flow flow_fun(...) {options: width="40\%" alt="my alt text"}

[moodymudskipper]

Used flow_embed() in the end in flow 0.2