Skip to content

Commit 085aebd

Browse files
HenrikBengtssonHenrikBengtsson
committed
Add vignette (from OVERVIEW.md)
1 parent c1326f6 commit 085aebd

24 files changed

+473
-18
lines changed

‎.Rbuildignore‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,5 @@ Rplots.pdf$
5858
^.ghi
5959
^.issues
6060
^last.dump*
61-
62-
vignettes/
63-
^.*.gif$
61+
^imgs
62+
^.*.bob$

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@
44
.local
55
inst/doc
66
.make/README.md.rsp
7+

‎DESCRIPTION‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
Package: progressr
2-
Version: 0.3.0-9000
2+
Version: 0.4.0
33
Title: A Unifying API for Progress Updates
44
Description: A minimal, unifying API for scripts and packages to report progress updates from anywhere including when using parallel processing. The package is designed such that the developer can to focus on what progress should be reported on without having to worry about how to present it. The end user has full control of how, where, and when to render these progress updates, e.g. in the terminal using 'utils::txtProgressBar()' or 'progress::progress_bar()', in a graphical user interface using 'utils::winProgressBar()', 'tcltk::tkProgressBar()' or 'shiny::withProgress()', via the speakers using 'beep::beepr()', or on a file system via the size of a file. Anyone can add additional, customized, progression handlers. The 'progressr' package uses R's condition framework for signaling progress updated. Because of this, progress can be reported from almost anywhere in R, e.g. from classical for and while loops, from map-reduce APIs like the 'lapply()' family of functions, 'purrr', 'plyr', and 'foreach'. It will also work with parallel processing via the 'future' framework, e.g. 'future.apply::future_lapply()', 'furrr::map()', and 'foreach' with 'doFuture'. The package is compatible with Shiny applications.
55
Authors@R: c(
@@ -22,7 +22,10 @@ Suggests:
2222
future (>= 1.16.0),
2323
future.apply,
2424
furrr,
25-
shiny
25+
shiny,
26+
commonmark,
27+
tools
28+
VignetteBuilder: progressr
2629
URL: https://github.com/HenrikBengtsson/progressr
2730
BugReports: https://github.com/HenrikBengtsson/progressr/issues
2831
RoxygenNote: 7.0.2

‎Makefile‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
11
include .make/Makefile
2+
3+
vignettes/progressr-intro.md: OVERVIEW.md vignettes/incl/clean.css
4+
sed -i '/%\\Vignette/!d' $@
5+
echo "<!-- DO NOT EDIT THIS FILE! Edit 'OVERVIEW.md' instead and then rebuild this file with 'make vigs' -->" >> $@
6+
cat $< >> $@
7+
8+
vigs: vignettes/progressr-intro.md

‎NEWS‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Package: progressr
22
==================
33

4-
Version: 0.3.0-9000 [2020-01-21]
4+
Version: 0.4.0 [2020-01-22]
55

66
SIGNIFICANT CHANGES:
77

‎OVERVIEW.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
![Life cycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)
1+
![Life cycle: experimental](imgs/lifecycle-experimental-orange.svg)
22

33
The **[progressr]** package provides a minimal API for reporting progress updates in [R](https://www.r-project.org/). The design is to separate the representation of progress updates from how they are presented. What type of progress to signal is controlled by the developer. How these progress updates are rendered is controlled by the end user. For instance, some users may prefer visual feedback such as a horizontal progress bar in the terminal, whereas others may prefer auditory feedback.
44

55

6-
<img src="incl/three_in_chinese.gif" alt="Three strokes writing three in Chinese" style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
6+
<img src="imgs/three_in_chinese.gif" alt="Three strokes writing three in Chinese" style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
77

88
Design motto:
99

@@ -291,7 +291,7 @@ When using the **progressr** package, progression updates are communicated via R
291291

292292

293293

294-
![](vignettes/figures/slow_sum.svg)
294+
![](imgs/slow_sum.svg)
295295

296296
_Figure: Sequence diagram illustrating how signaled progression conditions are captured by `with_progress()` and relayed to the two progression handlers 'progress' (a progress bar in the terminal) and 'beepr' (auditory) that the end user has chosen._
297297

‎R/vignette_engine.R‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
register_vignette_engine_during_build_only <- function(pkgname) {
2+
# Are vignette engines supported?
3+
if (getRversion() < "3.0.0") return() # Nope!
4+
5+
## HACK: Only register vignette engine progressr::selfonly during R CMD build
6+
if (Sys.getenv("R_CMD") == "") return()
7+
8+
tools::vignetteEngine("selfonly", package = "progressr", pattern = "[.]md$",
9+
weave = function(file, ...) {
10+
output <- sprintf("%s.html", tools::file_path_sans_ext(basename(file)))
11+
md <- readLines(file)
12+
13+
title <- grep("%\\VignetteIndexEntry{", md, fixed = TRUE, value = TRUE)
14+
title <- gsub(".*[{](.*)[}].*", "\\1", title)
15+
16+
md <- grep("%\\\\Vignette", md, invert = TRUE, value = TRUE)
17+
18+
## Inject vignette title
19+
md <- c(sprintf("# %s\n\n", title), md)
20+
21+
html <- commonmark::markdown_html(md,
22+
smart = FALSE,
23+
extensions = "table",
24+
normalize = FALSE)
25+
26+
## Inject HTML environment
27+
html <- c("<!DOCTYPE html>",
28+
"<html lang=\"en\">",
29+
"<head>",
30+
sprintf("<title>%s</title>", title),
31+
"<style>",
32+
readLines("incl/clean.css", warn = FALSE),
33+
"</style>",
34+
"</head>",
35+
"<body>", html, "</body>",
36+
"</html>")
37+
38+
writeLines(html, con = output)
39+
output
40+
},
41+
42+
tangle = function(file, ...) {
43+
## As of R 3.3.2, vignette engines must produce tangled output, but as
44+
## long as it contains all comments then 'R CMD build' will drop it.
45+
output <- sprintf("%s.R", tools::file_path_sans_ext(basename(file)))
46+
cat(sprintf("### This is an R script tangled from %s\n",
47+
sQuote(basename(file))), file = output)
48+
output
49+
}
50+
)
51+
}
52+

‎R/zzz.R‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,5 @@
22
if (in_r_cmd_check()) {
33
options(progressr.demo.delay = 0.0)
44
}
5+
register_vignette_engine_during_build_only(pkgname)
56
}

‎README.md‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
The **[progressr]** package provides a minimal API for reporting progress updates in [R](https://www.r-project.org/). The design is to separate the representation of progress updates from how they are presented. What type of progress to signal is controlled by the developer. How these progress updates are rendered is controlled by the end user. For instance, some users may prefer visual feedback such as a horizontal progress bar in the terminal, whereas others may prefer auditory feedback.
66

77

8-
<img src="incl/three_in_chinese.gif" alt="Three strokes writing three in Chinese" style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
8+
<img src="figures/three_in_chinese.gif" alt="Three strokes writing three in Chinese" style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
99

1010
Design motto:
1111

@@ -293,7 +293,7 @@ When using the **progressr** package, progression updates are communicated via R
293293

294294

295295

296-
![](vignettes/figures/slow_sum.svg)
296+
![](figures/slow_sum.svg)
297297

298298
_Figure: Sequence diagram illustrating how signaled progression conditions are captured by `with_progress()` and relayed to the two progression handlers 'progress' (a progress bar in the terminal) and 'beepr' (auditory) that the end user has chosen._
299299

@@ -339,13 +339,6 @@ R package progressr is only available via [GitHub](https://github.com/HenrikBeng
339339
remotes::install_github("HenrikBengtsson/progressr")
340340
```
341341

342-
### Pre-release version
343-
344-
To install the pre-release version that is available in Git branch `develop` on GitHub, use:
345-
```r
346-
remotes::install_github("HenrikBengtsson/progressr@develop")
347-
```
348-
This will install the package from source.
349342

350343

351344

‎imgs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
inst/doc/imgs

0 commit comments

Comments
 (0)