From 18d6c8b3ab725a7a1129f38fd1788a80c8d98bd8 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 09:36:32 -0400 Subject: [PATCH 01/21] render_docs(autolink = TRUE) uses downlit --- DESCRIPTION | 3 ++- NEWS.md | 1 + R/render_docs.R | 27 ++++++++++++++++++++++++++- man-roxygen/altdoc_freeze.R | 2 +- man/render_docs.Rd | 10 +++++++++- 5 files changed, 39 insertions(+), 4 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index f8f107b7..011696d1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Type: Package Package: altdoc Title: Package Documentation Websites with 'Quarto', 'Docsify', 'Docute', or 'MkDocs' -Version: 0.3.0.9002 +Version: 0.3.0.9003 Authors@R: c(person(given = "Etienne", family = "Bacher", @@ -24,6 +24,7 @@ Imports: cli, desc, evaluate, + downlit, fs, quarto, tools, diff --git a/NEWS.md b/NEWS.md index 211375a7..6861154b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -17,6 +17,7 @@ execute: freeze: auto ``` +* `render_docs(autolink = TRUE)` uses the `downlit` package to automatically link function calls to their documentation on the web. ### Other changes diff --git a/R/render_docs.R b/R/render_docs.R index 5e120714..e9509c28 100644 --- a/R/render_docs.R +++ b/R/render_docs.R @@ -7,6 +7,7 @@ #' @param verbose Logical. Print Rmarkdown or Quarto rendering output. #' @param parallel Logical. Render man pages and vignettes in parallel using the `future` framework. In addition to setting this argument to TRUE, users must define the parallelism plan in `future`. See the examples section below. #' @param freeze Logical. If TRUE and a man page or vignette has not changed since the last call to `render_docs()`, that file is skipped. File hashes are stored in `altdoc/freeze.rds`. If that file is deleted, all man pages and vignettes will be rendered anew. +#' @param autolink Logical. If TRUE use the `downlit` package to link function names and help calls from vignettes and man pages to documentation page on the web. #' @inheritParams setup_docs #' @export #' @@ -44,7 +45,7 @@ #' render_docs(parallel = TRUE) #' #' } -render_docs <- function(path = ".", verbose = FALSE, parallel = FALSE, freeze = FALSE) { +render_docs <- function(path = ".", verbose = FALSE, parallel = FALSE, freeze = FALSE, autolink = TRUE) { path <- .convert_path(path) tool <- .doc_type(path) @@ -92,6 +93,7 @@ render_docs <- function(path = ".", verbose = FALSE, parallel = FALSE, freeze = cli::cli_h1("Vignettes") fail_vignettes <- .import_vignettes(src_dir = path, tar_dir = docs_dir, tool = tool, verbose = verbose, parallel = parallel, freeze = freeze) + # Error so that CI fails if (length(fail_vignettes) > 0 & length(fail_man) > 0) { cli::cli_abort("There were some failures when rendering vignettes and man pages.") @@ -104,6 +106,29 @@ render_docs <- function(path = ".", verbose = FALSE, parallel = FALSE, freeze = cli::cli_h1("Update HTML") .import_settings(path = path, tool = tool, verbose = verbose, freeze = freeze) + if (isTRUE(autolink)) { + cli::cli_h1("Auto-Link") + html_files <- c(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), + fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$")) + for (h in html_files) { + downlit::downlit_html_path(h, h) + } + h <- fs::path_join(c(path, "docs/index.html")) + if (fs::file_exists(h)) { + downlit::downlit_html_path(h, h) + } + + md_files <- c(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), + fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$")) + for (m in md_files) { + downlit::downlit_html_path(m, m) + } + m <- fs::path_join(c(path, "docs/README.md")) + if (fs::file_exists(m)) { + downlit::downlit_html_path(m, m) + } + } + cli::cli_h1("Complete") cli::cli_alert_success("Documentation updated.") } diff --git a/man-roxygen/altdoc_freeze.R b/man-roxygen/altdoc_freeze.R index b54cbd04..f6f5e355 100644 --- a/man-roxygen/altdoc_freeze.R +++ b/man-roxygen/altdoc_freeze.R @@ -1,4 +1,4 @@ -#' @section Freeze +#' @section Freeze: #' #' When working on a package, running `render_docs()` to preview changes can be a time-consuming road block. The argument `freeze = TRUE` tries to improve the experience by preventing rerendering of files that have not changed since the last time `render_docs()` was ran. Note that changes to package internals will not cause a rerender, so rerendering the entire docs can still be necessary. #' diff --git a/man/render_docs.Rd b/man/render_docs.Rd index b7437bbc..c3c84d58 100644 --- a/man/render_docs.Rd +++ b/man/render_docs.Rd @@ -4,7 +4,13 @@ \alias{render_docs} \title{Update documentation} \usage{ -render_docs(path = ".", verbose = FALSE, parallel = FALSE, freeze = FALSE) +render_docs( + path = ".", + verbose = FALSE, + parallel = FALSE, + freeze = FALSE, + autolink = TRUE +) } \arguments{ \item{path}{Path to the package root directory.} @@ -14,6 +20,8 @@ render_docs(path = ".", verbose = FALSE, parallel = FALSE, freeze = FALSE) \item{parallel}{Logical. Render man pages and vignettes in parallel using the \code{future} framework. In addition to setting this argument to TRUE, users must define the parallelism plan in \code{future}. See the examples section below.} \item{freeze}{Logical. If TRUE and a man page or vignette has not changed since the last call to \code{render_docs()}, that file is skipped. File hashes are stored in \code{altdoc/freeze.rds}. If that file is deleted, all man pages and vignettes will be rendered anew.} + +\item{autolink}{Logical. If TRUE use the \code{downlit} package to link function names and help calls from vignettes and man pages to documentation page on the web.} } \description{ Render and update the function reference manual, vignettes, README, NEWS, CHANGELOG, LICENSE, From f3df7bd492c5ac89fcda1f46f2eb8550525ed7e2 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 14:51:04 -0400 Subject: [PATCH 02/21] .autolink() as own function --- R/autolink.R | 22 ++++++++++++++++++++++ R/render_docs.R | 20 +------------------- 2 files changed, 23 insertions(+), 19 deletions(-) create mode 100644 R/autolink.R diff --git a/R/autolink.R b/R/autolink.R new file mode 100644 index 00000000..d34f5d63 --- /dev/null +++ b/R/autolink.R @@ -0,0 +1,22 @@ +.autolink <- function(path = ".") { + html_files <- c(tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), error = function(e) NULL), + tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$"), error = function(e) NULL)) + for (h in html_files) { + downlit::downlit_html_path(h, h) + } + h <- fs::path_join(c(path, "docs/index.html")) + if (fs::file_exists(h)) { + downlit::downlit_html_path(h, h) + } + + md_files <- c( + tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), error = function(e) NULL), + tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$"), error = function(e) NULL)) + for (m in md_files) { + downlit::downlit_html_path(m, m) + } + m <- fs::path_join(c(path, "docs/README.md")) + if (fs::file_exists(m)) { + downlit::downlit_html_path(m, m) + } +} diff --git a/R/render_docs.R b/R/render_docs.R index e9509c28..592ad752 100644 --- a/R/render_docs.R +++ b/R/render_docs.R @@ -108,25 +108,7 @@ render_docs <- function(path = ".", verbose = FALSE, parallel = FALSE, freeze = if (isTRUE(autolink)) { cli::cli_h1("Auto-Link") - html_files <- c(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), - fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$")) - for (h in html_files) { - downlit::downlit_html_path(h, h) - } - h <- fs::path_join(c(path, "docs/index.html")) - if (fs::file_exists(h)) { - downlit::downlit_html_path(h, h) - } - - md_files <- c(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), - fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$")) - for (m in md_files) { - downlit::downlit_html_path(m, m) - } - m <- fs::path_join(c(path, "docs/README.md")) - if (fs::file_exists(m)) { - downlit::downlit_html_path(m, m) - } + .autolink(path) } cli::cli_h1("Complete") From fe2a4f89d56224e75e595c3f155cbdda7ae121ad Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 14:57:44 -0400 Subject: [PATCH 03/21] do not modify home page, to pass tests --- R/autolink.R | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/R/autolink.R b/R/autolink.R index d34f5d63..7bd124e6 100644 --- a/R/autolink.R +++ b/R/autolink.R @@ -4,10 +4,10 @@ for (h in html_files) { downlit::downlit_html_path(h, h) } - h <- fs::path_join(c(path, "docs/index.html")) - if (fs::file_exists(h)) { - downlit::downlit_html_path(h, h) - } + # h <- fs::path_join(c(path, "docs/index.html")) + # if (fs::file_exists(h)) { + # downlit::downlit_html_path(h, h) + # } md_files <- c( tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), error = function(e) NULL), @@ -15,8 +15,8 @@ for (m in md_files) { downlit::downlit_html_path(m, m) } - m <- fs::path_join(c(path, "docs/README.md")) - if (fs::file_exists(m)) { - downlit::downlit_html_path(m, m) - } + # m <- fs::path_join(c(path, "docs/README.md")) + # if (fs::file_exists(m)) { + # downlit::downlit_html_path(m, m) + # } } From 2e855148e5fc5e2f8f34de5ed3ddc08290c0d2d2 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 15:31:04 -0400 Subject: [PATCH 04/21] autolink markdown --- R/autolink.R | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/R/autolink.R b/R/autolink.R index 7bd124e6..7920476c 100644 --- a/R/autolink.R +++ b/R/autolink.R @@ -10,10 +10,10 @@ # } md_files <- c( - tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), error = function(e) NULL), - tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$"), error = function(e) NULL)) + tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.md$"), error = function(e) NULL), + tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.md$"), error = function(e) NULL)) for (m in md_files) { - downlit::downlit_html_path(m, m) + downlit::downlit_md_path(m, m) } # m <- fs::path_join(c(path, "docs/README.md")) # if (fs::file_exists(m)) { From 9c006b95f1ff494267c31cf8fddb951371389976 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 15:36:25 -0400 Subject: [PATCH 05/21] pkgdown.yml --- altdoc/pkgdown.yml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 altdoc/pkgdown.yml diff --git a/altdoc/pkgdown.yml b/altdoc/pkgdown.yml new file mode 100644 index 00000000..7b2d9487 --- /dev/null +++ b/altdoc/pkgdown.yml @@ -0,0 +1,3 @@ +urls: + reference: https://altdoc.etiennebacher.com/man + article: https://altdoc.etiennebacher.com/vignettes From e27b146f38a4872e8e622acf92fc3fa8de7f8456 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 15:38:25 -0400 Subject: [PATCH 06/21] snapshots --- tests/testthat/_snaps/docsify/render_docs.md | 556 +++++++++---------- tests/testthat/_snaps/docute/render_docs.md | 556 +++++++++---------- tests/testthat/_snaps/mkdocs/render_docs.md | 406 +++++++------- 3 files changed, 747 insertions(+), 771 deletions(-) diff --git a/tests/testthat/_snaps/docsify/render_docs.md b/tests/testthat/_snaps/docsify/render_docs.md index 85ab45aa..2525afe4 100644 --- a/tests/testthat/_snaps/docsify/render_docs.md +++ b/tests/testthat/_snaps/docsify/render_docs.md @@ -128,311 +128,301 @@ Code .readlines("docs/man/hello_base.md") Output - [1] "" - [2] "" - [3] "# Base function" - [4] "" - [5] "## Description" - [6] "" - [7] "Base function" - [8] "" - [9] "## Usage" - [10] "" - [11] "
hello_base(x = 2)"                                
-      [12] "
" - [13] "" - [14] "## Arguments" - [15] "" - [16] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Details" - [28] "" - [29] "Some code with weird symbols: pl$when(condition) and" - [30] "pl$then(output)" - [31] "" - [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" - [33] "" - [34] "## Value" - [35] "" - [36] "Some value" - [37] "" - [38] "## Examples" - [39] "" - [40] "``` r" - [41] "library(testpkg.altdoc)" - [42] "" - [43] "hello_base()" - [44] "```" - [45] "" - [46] " [1] \"Hello, world!\"" - [47] "" - [48] "``` r" - [49] "mtcars$drat <- mtcars$drat + 1" - [50] "head(mtcars[[\"drat\"]], 2)" - [51] "```" - [52] "" - [53] " [1] 4.9 4.9" + [1] "# Base function" + [2] "" + [3] "## Description" + [4] "" + [5] "Base function" + [6] "" + [7] "## Usage" + [8] "" + [9] "
hello_base(x = 2)"                                                                                                                                                                                                                                                                
+      [10] "
" + [11] "" + [12] "## Arguments" + [13] "" + [14] "" + [15] "" + [16] "" + [19] "" + [22] "" + [23] "
" + [17] "x" + [18] "" + [20] "A parameter" + [21] "
" + [24] "" + [25] "## Details" + [26] "" + [27] "Some code with weird symbols: pl$when(condition) and" + [28] "pl$then(output)" + [29] "" + [30] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" + [31] "" + [32] "## Value" + [33] "" + [34] "Some value" + [35] "" + [36] "## Examples" + [37] "" + [38] "
"                                                                                                                                                                                                                                                                                           
+      [39] "library(testpkg.altdoc)"                                                                     
+      [40] ""                                                                                                                                                                                                                                                                                                  
+      [41] "hello_base()
" + [42] "" + [43] " [1] \"Hello, world!\"" + [44] "" + [45] "
"                                                                                                                                                                                                                                                                                           
+      [46] "mtcars$drat <- mtcars$drat + 1"                                              
+      [47] "head(mtcars[[\"drat\"]], 2)
" + [48] "" + [49] " [1] 4.9 4.9" --- Code .readlines("docs/man/hello_r6.md") Output - [1] "" - [2] "" - [3] "# Create a \"conductor\" tour" - [4] "" - [5] "## Description" - [6] "" - [7] "blah blah blah" - [8] "" - [9] "## Methods" - [10] "" - [11] "

" - [12] "Public methods" - [13] "

" - [14] "" - [36] "
" - [37] "" - [38] "" - [39] "" - [40] "

" - [41] "Method new()" - [42] "

" - [43] "
" - [44] "Usage" - [45] "
" - [46] "" - [47] "
hello_r6\\$new()
" - [48] "" - [49] "
" - [50] "Details" - [51] "
" - [52] "" - [53] "Initialise Conductor." - [54] "" - [55] "
" - [56] "" - [57] "" - [58] "" - [59] "

" - [60] "Method init()" - [61] "

" - [62] "
" - [63] "Usage" - [64] "
" - [65] "" - [66] "
hello_r6\\$init(session = NULL)
" - [67] "" - [68] "
" - [69] "Arguments" - [70] "
" - [71] "" - [72] "
" - [73] "
" - [74] "session" - [75] "
" - [76] "
" - [77] "A valid Shiny session. If NULL (default), the function" - [78] "attempts to get the session with" - [79] "shiny::getDefaultReactiveDomain()." - [80] "
" - [81] "
" - [82] "" - [83] "
" - [84] "Details" - [85] "
" - [86] "" - [87] "Initialise Conductor." - [88] "" - [89] "
" - [90] "" - [91] "" - [92] "" - [93] "

" - [94] "Method step()" - [95] "

" - [96] "
" - [97] "Usage" - [98] "
" - [99] "" - [100] "
hello_r6\\$step(title = NULL)
" - [101] "" - [102] "
" - [103] "Arguments" - [104] "
" - [105] "" - [106] "
" - [107] "
" - [108] "title" - [109] "
" - [110] "
" - [111] "Title of the popover." - [112] "
" - [113] "
" - [114] "" - [115] "
" - [116] "Details" - [117] "
" - [118] "" - [119] "Add a step in a Conductor tour." - [120] "" - [121] "
" - [122] "" - [123] "" - [124] "" - [125] "

" - [126] "Method clone()" - [127] "

" - [128] "" - [129] "The objects of this class are cloneable with this method." - [130] "" - [131] "
" - [132] "Usage" - [133] "
" - [134] "" - [135] "
hello_r6\\$clone(deep = FALSE)
" - [136] "" - [137] "
" - [138] "Arguments" - [139] "
" - [140] "" - [141] "
" - [142] "
" - [143] "deep" - [144] "
" - [145] "
" - [146] "Whether to make a deep clone." - [147] "
" - [148] "
" + [1] "# Create a \"conductor\" tour" + [2] "" + [3] "## Description" + [4] "" + [5] "blah blah blah" + [6] "" + [7] "## Methods" + [8] "" + [9] "

" + [10] "Public methods" + [11] "

" + [12] "" + [34] "
" + [35] "" + [36] "" + [37] "" + [38] "

" + [39] "Method new()" + [40] "

" + [41] "
" + [42] "Usage" + [43] "
" + [44] "" + [45] "
hello_r6\\$new()
" + [46] "" + [47] "
" + [48] "Details" + [49] "
" + [50] "" + [51] "Initialise Conductor." + [52] "" + [53] "
" + [54] "" + [55] "" + [56] "" + [57] "

" + [58] "Method init()" + [59] "

" + [60] "
" + [61] "Usage" + [62] "
" + [63] "" + [64] "
hello_r6\\$init(session = NULL)
" + [65] "" + [66] "
" + [67] "Arguments" + [68] "
" + [69] "" + [70] "
" + [71] "
" + [72] "session" + [73] "
" + [74] "
" + [75] "A valid Shiny session. If NULL (default), the function" + [76] "attempts to get the session with" + [77] "shiny::getDefaultReactiveDomain()." + [78] "
" + [79] "
" + [80] "" + [81] "
" + [82] "Details" + [83] "
" + [84] "" + [85] "Initialise Conductor." + [86] "" + [87] "
" + [88] "" + [89] "" + [90] "" + [91] "

" + [92] "Method step()" + [93] "

" + [94] "
" + [95] "Usage" + [96] "
" + [97] "" + [98] "
hello_r6\\$step(title = NULL)
" + [99] "" + [100] "
" + [101] "Arguments" + [102] "
" + [103] "" + [104] "
" + [105] "
" + [106] "title" + [107] "
" + [108] "
" + [109] "Title of the popover." + [110] "
" + [111] "
" + [112] "" + [113] "
" + [114] "Details" + [115] "
" + [116] "" + [117] "Add a step in a Conductor tour." + [118] "" + [119] "
" + [120] "" + [121] "" + [122] "" + [123] "

" + [124] "Method clone()" + [125] "

" + [126] "" + [127] "The objects of this class are cloneable with this method." + [128] "" + [129] "
" + [130] "Usage" + [131] "
" + [132] "" + [133] "
hello_r6\\$clone(deep = FALSE)
" + [134] "" + [135] "
" + [136] "Arguments" + [137] "
" + [138] "" + [139] "
" + [140] "
" + [141] "deep" + [142] "
" + [143] "
" + [144] "Whether to make a deep clone." + [145] "
" + [146] "
" --- Code .readlines("docs/man/examplesIf_true.md") Output - [1] "" - [2] "" - [3] "# Examples If TRUE" - [4] "" - [5] "## Description" - [6] "" - [7] "Examples If TRUE" - [8] "" - [9] "## Usage" - [10] "" - [11] "
examplesIf_true()"                                
-      [12] "
" - [13] "" - [14] "## Arguments" - [15] "" - [16] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Value" - [28] "" - [29] "Some value" - [30] "" - [31] "## Examples" - [32] "" - [33] "``` r" - [34] "library(testpkg.altdoc)" - [35] "" - [36] "" - [37] "examplesIf_true()" - [38] "```" - [39] "" - [40] " [1] \"Hello, world!\"" + [1] "# Examples If TRUE" + [2] "" + [3] "## Description" + [4] "" + [5] "Examples If TRUE" + [6] "" + [7] "## Usage" + [8] "" + [9] "
examplesIf_true()"                                                                                                                                                                                           
+      [10] "
" + [11] "" + [12] "## Arguments" + [13] "" + [14] "" + [15] "" + [16] "" + [19] "" + [22] "" + [23] "
" + [17] "x" + [18] "" + [20] "A parameter" + [21] "
" + [24] "" + [25] "## Value" + [26] "" + [27] "Some value" + [28] "" + [29] "## Examples" + [30] "" + [31] "
"                                                                                                                                                                                                                      
+      [32] "library(testpkg.altdoc)"
+      [33] ""                                                                                                                                                                                                                             
+      [34] ""                                                                                                                                                                                                                             
+      [35] "examplesIf_true()
" + [36] "" + [37] " [1] \"Hello, world!\"" --- Code .readlines("docs/man/examplesIf_false.md") Output - [1] "" - [2] "" - [3] "# Examples If FALSE" - [4] "" - [5] "## Description" - [6] "" - [7] "Examples If FALSE" - [8] "" - [9] "## Usage" - [10] "" - [11] "
examplesIf_false()"                               
-      [12] "
" - [13] "" - [14] "## Arguments" - [15] "" - [16] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Value" - [28] "" - [29] "Some value" - [30] "" - [31] "## Examples" - [32] "" - [33] "``` r" - [34] "library(testpkg.altdoc)" - [35] "" - [36] "" - [37] "examplesIf_false()" - [38] "```" + [1] "# Examples If FALSE" + [2] "" + [3] "## Description" + [4] "" + [5] "Examples If FALSE" + [6] "" + [7] "## Usage" + [8] "" + [9] "
examplesIf_false()"                                                                                                                                                                                          
+      [10] "
" + [11] "" + [12] "## Arguments" + [13] "" + [14] "" + [15] "" + [16] "" + [19] "" + [22] "" + [23] "
" + [17] "x" + [18] "" + [20] "A parameter" + [21] "
" + [24] "" + [25] "## Value" + [26] "" + [27] "Some value" + [28] "" + [29] "## Examples" + [30] "" + [31] "
"                                                                                                                                                                                                                      
+      [32] "library(testpkg.altdoc)"
+      [33] ""                                                                                                                                                                                                                             
+      [34] ""                                                                                                                                                                                                                             
+      [35] "examplesIf_false()
" --- Code .readlines("docs/vignettes/test.md") Output - [1] "# test" "" - [3] "" "``` r" - [5] "library(testpkg.altdoc)" "```" - [7] "" "hello there" + [1] "# test" + [2] "" + [3] "
"                                                                                                                                                                                                                            
+      [4] "library(testpkg.altdoc)
" + [5] "" + [6] "hello there" diff --git a/tests/testthat/_snaps/docute/render_docs.md b/tests/testthat/_snaps/docute/render_docs.md index 8aba0fef..6da044bb 100644 --- a/tests/testthat/_snaps/docute/render_docs.md +++ b/tests/testthat/_snaps/docute/render_docs.md @@ -119,311 +119,301 @@ Code .readlines("docs/man/hello_base.md") Output - [1] "" - [2] "" - [3] "# Base function" - [4] "" - [5] "## Description" - [6] "" - [7] "Base function" - [8] "" - [9] "## Usage" - [10] "" - [11] "
hello_base(x = 2)"                                
-      [12] "
" - [13] "" - [14] "## Arguments" - [15] "" - [16] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Details" - [28] "" - [29] "Some code with weird symbols: pl$when(condition) and" - [30] "pl$then(output)" - [31] "" - [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" - [33] "" - [34] "## Value" - [35] "" - [36] "Some value" - [37] "" - [38] "## Examples" - [39] "" - [40] "``` r" - [41] "library(testpkg.altdoc)" - [42] "" - [43] "hello_base()" - [44] "```" - [45] "" - [46] " [1] \"Hello, world!\"" - [47] "" - [48] "``` r" - [49] "mtcars$drat <- mtcars$drat + 1" - [50] "head(mtcars[[\"drat\"]], 2)" - [51] "```" - [52] "" - [53] " [1] 4.9 4.9" + [1] "# Base function" + [2] "" + [3] "## Description" + [4] "" + [5] "Base function" + [6] "" + [7] "## Usage" + [8] "" + [9] "
hello_base(x = 2)"                                                                                                                                                                                                                                                                
+      [10] "
" + [11] "" + [12] "## Arguments" + [13] "" + [14] "" + [15] "" + [16] "" + [19] "" + [22] "" + [23] "
" + [17] "x" + [18] "" + [20] "A parameter" + [21] "
" + [24] "" + [25] "## Details" + [26] "" + [27] "Some code with weird symbols: pl$when(condition) and" + [28] "pl$then(output)" + [29] "" + [30] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" + [31] "" + [32] "## Value" + [33] "" + [34] "Some value" + [35] "" + [36] "## Examples" + [37] "" + [38] "
"                                                                                                                                                                                                                                                                                           
+      [39] "library(testpkg.altdoc)"                                                                     
+      [40] ""                                                                                                                                                                                                                                                                                                  
+      [41] "hello_base()
" + [42] "" + [43] " [1] \"Hello, world!\"" + [44] "" + [45] "
"                                                                                                                                                                                                                                                                                           
+      [46] "mtcars$drat <- mtcars$drat + 1"                                              
+      [47] "head(mtcars[[\"drat\"]], 2)
" + [48] "" + [49] " [1] 4.9 4.9" --- Code .readlines("docs/man/hello_r6.md") Output - [1] "" - [2] "" - [3] "# Create a \"conductor\" tour" - [4] "" - [5] "## Description" - [6] "" - [7] "blah blah blah" - [8] "" - [9] "## Methods" - [10] "" - [11] "

" - [12] "Public methods" - [13] "

" - [14] "" - [36] "
" - [37] "" - [38] "" - [39] "" - [40] "

" - [41] "Method new()" - [42] "

" - [43] "
" - [44] "Usage" - [45] "
" - [46] "" - [47] "
hello_r6\\$new()
" - [48] "" - [49] "
" - [50] "Details" - [51] "
" - [52] "" - [53] "Initialise Conductor." - [54] "" - [55] "
" - [56] "" - [57] "" - [58] "" - [59] "

" - [60] "Method init()" - [61] "

" - [62] "
" - [63] "Usage" - [64] "
" - [65] "" - [66] "
hello_r6\\$init(session = NULL)
" - [67] "" - [68] "
" - [69] "Arguments" - [70] "
" - [71] "" - [72] "
" - [73] "
" - [74] "session" - [75] "
" - [76] "
" - [77] "A valid Shiny session. If NULL (default), the function" - [78] "attempts to get the session with" - [79] "shiny::getDefaultReactiveDomain()." - [80] "
" - [81] "
" - [82] "" - [83] "
" - [84] "Details" - [85] "
" - [86] "" - [87] "Initialise Conductor." - [88] "" - [89] "
" - [90] "" - [91] "" - [92] "" - [93] "

" - [94] "Method step()" - [95] "

" - [96] "
" - [97] "Usage" - [98] "
" - [99] "" - [100] "
hello_r6\\$step(title = NULL)
" - [101] "" - [102] "
" - [103] "Arguments" - [104] "
" - [105] "" - [106] "
" - [107] "
" - [108] "title" - [109] "
" - [110] "
" - [111] "Title of the popover." - [112] "
" - [113] "
" - [114] "" - [115] "
" - [116] "Details" - [117] "
" - [118] "" - [119] "Add a step in a Conductor tour." - [120] "" - [121] "
" - [122] "" - [123] "" - [124] "" - [125] "

" - [126] "Method clone()" - [127] "

" - [128] "" - [129] "The objects of this class are cloneable with this method." - [130] "" - [131] "
" - [132] "Usage" - [133] "
" - [134] "" - [135] "
hello_r6\\$clone(deep = FALSE)
" - [136] "" - [137] "
" - [138] "Arguments" - [139] "
" - [140] "" - [141] "
" - [142] "
" - [143] "deep" - [144] "
" - [145] "
" - [146] "Whether to make a deep clone." - [147] "
" - [148] "
" + [1] "# Create a \"conductor\" tour" + [2] "" + [3] "## Description" + [4] "" + [5] "blah blah blah" + [6] "" + [7] "## Methods" + [8] "" + [9] "

" + [10] "Public methods" + [11] "

" + [12] "" + [34] "
" + [35] "" + [36] "" + [37] "" + [38] "

" + [39] "Method new()" + [40] "

" + [41] "
" + [42] "Usage" + [43] "
" + [44] "" + [45] "
hello_r6\\$new()
" + [46] "" + [47] "
" + [48] "Details" + [49] "
" + [50] "" + [51] "Initialise Conductor." + [52] "" + [53] "
" + [54] "" + [55] "" + [56] "" + [57] "

" + [58] "Method init()" + [59] "

" + [60] "
" + [61] "Usage" + [62] "
" + [63] "" + [64] "
hello_r6\\$init(session = NULL)
" + [65] "" + [66] "
" + [67] "Arguments" + [68] "
" + [69] "" + [70] "
" + [71] "
" + [72] "session" + [73] "
" + [74] "
" + [75] "A valid Shiny session. If NULL (default), the function" + [76] "attempts to get the session with" + [77] "shiny::getDefaultReactiveDomain()." + [78] "
" + [79] "
" + [80] "" + [81] "
" + [82] "Details" + [83] "
" + [84] "" + [85] "Initialise Conductor." + [86] "" + [87] "
" + [88] "" + [89] "" + [90] "" + [91] "

" + [92] "Method step()" + [93] "

" + [94] "
" + [95] "Usage" + [96] "
" + [97] "" + [98] "
hello_r6\\$step(title = NULL)
" + [99] "" + [100] "
" + [101] "Arguments" + [102] "
" + [103] "" + [104] "
" + [105] "
" + [106] "title" + [107] "
" + [108] "
" + [109] "Title of the popover." + [110] "
" + [111] "
" + [112] "" + [113] "
" + [114] "Details" + [115] "
" + [116] "" + [117] "Add a step in a Conductor tour." + [118] "" + [119] "
" + [120] "" + [121] "" + [122] "" + [123] "

" + [124] "Method clone()" + [125] "

" + [126] "" + [127] "The objects of this class are cloneable with this method." + [128] "" + [129] "
" + [130] "Usage" + [131] "
" + [132] "" + [133] "
hello_r6\\$clone(deep = FALSE)
" + [134] "" + [135] "
" + [136] "Arguments" + [137] "
" + [138] "" + [139] "
" + [140] "
" + [141] "deep" + [142] "
" + [143] "
" + [144] "Whether to make a deep clone." + [145] "
" + [146] "
" --- Code .readlines("docs/man/examplesIf_true.md") Output - [1] "" - [2] "" - [3] "# Examples If TRUE" - [4] "" - [5] "## Description" - [6] "" - [7] "Examples If TRUE" - [8] "" - [9] "## Usage" - [10] "" - [11] "
examplesIf_true()"                                
-      [12] "
" - [13] "" - [14] "## Arguments" - [15] "" - [16] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Value" - [28] "" - [29] "Some value" - [30] "" - [31] "## Examples" - [32] "" - [33] "``` r" - [34] "library(testpkg.altdoc)" - [35] "" - [36] "" - [37] "examplesIf_true()" - [38] "```" - [39] "" - [40] " [1] \"Hello, world!\"" + [1] "# Examples If TRUE" + [2] "" + [3] "## Description" + [4] "" + [5] "Examples If TRUE" + [6] "" + [7] "## Usage" + [8] "" + [9] "
examplesIf_true()"                                                                                                                                                                                           
+      [10] "
" + [11] "" + [12] "## Arguments" + [13] "" + [14] "" + [15] "" + [16] "" + [19] "" + [22] "" + [23] "
" + [17] "x" + [18] "" + [20] "A parameter" + [21] "
" + [24] "" + [25] "## Value" + [26] "" + [27] "Some value" + [28] "" + [29] "## Examples" + [30] "" + [31] "
"                                                                                                                                                                                                                      
+      [32] "library(testpkg.altdoc)"
+      [33] ""                                                                                                                                                                                                                             
+      [34] ""                                                                                                                                                                                                                             
+      [35] "examplesIf_true()
" + [36] "" + [37] " [1] \"Hello, world!\"" --- Code .readlines("docs/man/examplesIf_false.md") Output - [1] "" - [2] "" - [3] "# Examples If FALSE" - [4] "" - [5] "## Description" - [6] "" - [7] "Examples If FALSE" - [8] "" - [9] "## Usage" - [10] "" - [11] "
examplesIf_false()"                               
-      [12] "
" - [13] "" - [14] "## Arguments" - [15] "" - [16] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Value" - [28] "" - [29] "Some value" - [30] "" - [31] "## Examples" - [32] "" - [33] "``` r" - [34] "library(testpkg.altdoc)" - [35] "" - [36] "" - [37] "examplesIf_false()" - [38] "```" + [1] "# Examples If FALSE" + [2] "" + [3] "## Description" + [4] "" + [5] "Examples If FALSE" + [6] "" + [7] "## Usage" + [8] "" + [9] "
examplesIf_false()"                                                                                                                                                                                          
+      [10] "
" + [11] "" + [12] "## Arguments" + [13] "" + [14] "" + [15] "" + [16] "" + [19] "" + [22] "" + [23] "
" + [17] "x" + [18] "" + [20] "A parameter" + [21] "
" + [24] "" + [25] "## Value" + [26] "" + [27] "Some value" + [28] "" + [29] "## Examples" + [30] "" + [31] "
"                                                                                                                                                                                                                      
+      [32] "library(testpkg.altdoc)"
+      [33] ""                                                                                                                                                                                                                             
+      [34] ""                                                                                                                                                                                                                             
+      [35] "examplesIf_false()
" --- Code .readlines("docs/vignettes/test.md") Output - [1] "# test" "" - [3] "" "``` r" - [5] "library(testpkg.altdoc)" "```" - [7] "" "hello there" + [1] "# test" + [2] "" + [3] "
"                                                                                                                                                                                                                            
+      [4] "library(testpkg.altdoc)
" + [5] "" + [6] "hello there" diff --git a/tests/testthat/_snaps/mkdocs/render_docs.md b/tests/testthat/_snaps/mkdocs/render_docs.md index b7fb2385..b1d81470 100644 --- a/tests/testthat/_snaps/mkdocs/render_docs.md +++ b/tests/testthat/_snaps/mkdocs/render_docs.md @@ -18,221 +18,217 @@ Code .readlines("docs/man/hello_base.md") Output - [1] "" - [2] "" - [3] "# Base function" - [4] "" - [5] "## Description" - [6] "" - [7] "Base function" - [8] "" - [9] "## Usage" - [10] "" - [11] "
hello_base(x = 2)"                                
-      [12] "
" - [13] "" - [14] "## Arguments" - [15] "" - [16] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Details" - [28] "" - [29] "Some code with weird symbols: pl$when(condition) and" - [30] "pl$then(output)" - [31] "" - [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" - [33] "" - [34] "## Value" - [35] "" - [36] "Some value" - [37] "" - [38] "## Examples" - [39] "" - [40] "``` r" - [41] "library(testpkg.altdoc)" - [42] "" - [43] "hello_base()" - [44] "```" - [45] "" - [46] " [1] \"Hello, world!\"" - [47] "" - [48] "``` r" - [49] "mtcars$drat <- mtcars$drat + 1" - [50] "head(mtcars[[\"drat\"]], 2)" - [51] "```" - [52] "" - [53] " [1] 4.9 4.9" + [1] "# Base function" + [2] "" + [3] "## Description" + [4] "" + [5] "Base function" + [6] "" + [7] "## Usage" + [8] "" + [9] "
hello_base(x = 2)"                                                                                                                                                                                                                                                                
+      [10] "
" + [11] "" + [12] "## Arguments" + [13] "" + [14] "" + [15] "" + [16] "" + [19] "" + [22] "" + [23] "
" + [17] "x" + [18] "" + [20] "A parameter" + [21] "
" + [24] "" + [25] "## Details" + [26] "" + [27] "Some code with weird symbols: pl$when(condition) and" + [28] "pl$then(output)" + [29] "" + [30] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" + [31] "" + [32] "## Value" + [33] "" + [34] "Some value" + [35] "" + [36] "## Examples" + [37] "" + [38] "
"                                                                                                                                                                                                                                                                                           
+      [39] "library(testpkg.altdoc)"                                                                     
+      [40] ""                                                                                                                                                                                                                                                                                                  
+      [41] "hello_base()
" + [42] "" + [43] " [1] \"Hello, world!\"" + [44] "" + [45] "
"                                                                                                                                                                                                                                                                                           
+      [46] "mtcars$drat <- mtcars$drat + 1"                                              
+      [47] "head(mtcars[[\"drat\"]], 2)
" + [48] "" + [49] " [1] 4.9 4.9" --- Code .readlines("docs/man/hello_r6.md") Output - [1] "" - [2] "" - [3] "# Create a \"conductor\" tour" - [4] "" - [5] "## Description" - [6] "" - [7] "blah blah blah" - [8] "" - [9] "## Methods" - [10] "" - [11] "

" - [12] "Public methods" - [13] "

" - [14] "" - [36] "
" - [37] "" - [38] "" - [39] "" - [40] "

" - [41] "Method new()" - [42] "

" - [43] "
" - [44] "Usage" - [45] "
" - [46] "" - [47] "
hello_r6\\$new()
" - [48] "" - [49] "
" - [50] "Details" - [51] "
" - [52] "" - [53] "Initialise Conductor." - [54] "" - [55] "
" - [56] "" - [57] "" - [58] "" - [59] "

" - [60] "Method init()" - [61] "

" - [62] "
" - [63] "Usage" - [64] "
" - [65] "" - [66] "
hello_r6\\$init(session = NULL)
" - [67] "" - [68] "
" - [69] "Arguments" - [70] "
" - [71] "" - [72] "
" - [73] "
" - [74] "session" - [75] "
" - [76] "
" - [77] "A valid Shiny session. If NULL (default), the function" - [78] "attempts to get the session with" - [79] "shiny::getDefaultReactiveDomain()." - [80] "
" - [81] "
" - [82] "" - [83] "
" - [84] "Details" - [85] "
" - [86] "" - [87] "Initialise Conductor." - [88] "" - [89] "
" - [90] "" - [91] "" - [92] "" - [93] "

" - [94] "Method step()" - [95] "

" - [96] "
" - [97] "Usage" - [98] "
" - [99] "" - [100] "
hello_r6\\$step(title = NULL)
" - [101] "" - [102] "
" - [103] "Arguments" - [104] "
" - [105] "" - [106] "
" - [107] "
" - [108] "title" - [109] "
" - [110] "
" - [111] "Title of the popover." - [112] "
" - [113] "
" - [114] "" - [115] "
" - [116] "Details" - [117] "
" - [118] "" - [119] "Add a step in a Conductor tour." - [120] "" - [121] "
" - [122] "" - [123] "" - [124] "" - [125] "

" - [126] "Method clone()" - [127] "

" - [128] "" - [129] "The objects of this class are cloneable with this method." - [130] "" - [131] "
" - [132] "Usage" - [133] "
" - [134] "" - [135] "
hello_r6\\$clone(deep = FALSE)
" - [136] "" - [137] "
" - [138] "Arguments" - [139] "
" - [140] "" - [141] "
" - [142] "
" - [143] "deep" - [144] "
" - [145] "
" - [146] "Whether to make a deep clone." - [147] "
" - [148] "
" + [1] "# Create a \"conductor\" tour" + [2] "" + [3] "## Description" + [4] "" + [5] "blah blah blah" + [6] "" + [7] "## Methods" + [8] "" + [9] "

" + [10] "Public methods" + [11] "

" + [12] "" + [34] "
" + [35] "" + [36] "" + [37] "" + [38] "

" + [39] "Method new()" + [40] "

" + [41] "
" + [42] "Usage" + [43] "
" + [44] "" + [45] "
hello_r6\\$new()
" + [46] "" + [47] "
" + [48] "Details" + [49] "
" + [50] "" + [51] "Initialise Conductor." + [52] "" + [53] "
" + [54] "" + [55] "" + [56] "" + [57] "

" + [58] "Method init()" + [59] "

" + [60] "
" + [61] "Usage" + [62] "
" + [63] "" + [64] "
hello_r6\\$init(session = NULL)
" + [65] "" + [66] "
" + [67] "Arguments" + [68] "
" + [69] "" + [70] "
" + [71] "
" + [72] "session" + [73] "
" + [74] "
" + [75] "A valid Shiny session. If NULL (default), the function" + [76] "attempts to get the session with" + [77] "shiny::getDefaultReactiveDomain()." + [78] "
" + [79] "
" + [80] "" + [81] "
" + [82] "Details" + [83] "
" + [84] "" + [85] "Initialise Conductor." + [86] "" + [87] "
" + [88] "" + [89] "" + [90] "" + [91] "

" + [92] "Method step()" + [93] "

" + [94] "
" + [95] "Usage" + [96] "
" + [97] "" + [98] "
hello_r6\\$step(title = NULL)
" + [99] "" + [100] "
" + [101] "Arguments" + [102] "
" + [103] "" + [104] "
" + [105] "
" + [106] "title" + [107] "
" + [108] "
" + [109] "Title of the popover." + [110] "
" + [111] "
" + [112] "" + [113] "
" + [114] "Details" + [115] "
" + [116] "" + [117] "Add a step in a Conductor tour." + [118] "" + [119] "
" + [120] "" + [121] "" + [122] "" + [123] "

" + [124] "Method clone()" + [125] "

" + [126] "" + [127] "The objects of this class are cloneable with this method." + [128] "" + [129] "
" + [130] "Usage" + [131] "
" + [132] "" + [133] "
hello_r6\\$clone(deep = FALSE)
" + [134] "" + [135] "
" + [136] "Arguments" + [137] "
" + [138] "" + [139] "
" + [140] "
" + [141] "deep" + [142] "
" + [143] "
" + [144] "Whether to make a deep clone." + [145] "
" + [146] "
" --- Code .readlines("docs/vignettes/test.md") Output - [1] "# test" "" - [3] "" "``` r" - [5] "library(testpkg.altdoc)" "```" - [7] "" "hello there" + [1] "# test" + [2] "" + [3] "
"                                                                                                                                                                                                                            
+      [4] "library(testpkg.altdoc)
" + [5] "" + [6] "hello there" From c130320e78b32de3720bbe766f856ad217073449 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 15:46:13 -0400 Subject: [PATCH 07/21] workflow --- .github/workflows/altdoc.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/altdoc.yaml b/.github/workflows/altdoc.yaml index 8f4c8aaf..93f360c0 100644 --- a/.github/workflows/altdoc.yaml +++ b/.github/workflows/altdoc.yaml @@ -40,7 +40,7 @@ jobs: install.packages(".", repos = NULL, type = "source") install.packages("pkgload") pkgload::load_all() - altdoc::render_docs(parallel = TRUE, freeze = FALSE) + altdoc::render_docs(parallel = FALSE, freeze = FALSE) shell: Rscript {0} - name: Deploy to GitHub pages 🚀 From fff94f564ceca576e798ad26474a5c73b34057c9 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 15:59:04 -0400 Subject: [PATCH 08/21] avoid warning --- R/settings_docute.R | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/R/settings_docute.R b/R/settings_docute.R index e2b0cca9..2ee3f7c7 100644 --- a/R/settings_docute.R +++ b/R/settings_docute.R @@ -60,8 +60,10 @@ tmp <- sprintf("{title: '%s', link: '%s'}", titles, fn_vignettes) tmp <- paste(tmp, collapse = ", ") sidebar <- paste(sidebar, collapse = "\n") - sidebar <- gsub("\\$ALTDOC_VIGNETTE_BLOCK", "%s", sidebar) - sidebar <- sprintf(sidebar, tmp) + if (isTRUE(grepl("\\$ALTDOC_VIGNETTE_BLOCK", sidebar))) { + sidebar <- gsub("\\$ALTDOC_VIGNETTE_BLOCK", "%s", sidebar) + sidebar <- sprintf(sidebar, tmp) + } sidebar <- strsplit(sidebar, "\n")[[1]] } else { sidebar <- sidebar[!grepl("\\$ALTDOC_VIGNETTE_BLOCK", sidebar)] @@ -81,8 +83,10 @@ tmp <- sprintf("{title: '%s', link: '%s'}", titles, fn_man) tmp <- paste(tmp, collapse = ", ") sidebar <- paste(sidebar, collapse = "\n") - sidebar <- gsub("\\$ALTDOC_MAN_BLOCK", "%s", sidebar) - sidebar <- sprintf(sidebar, tmp) + if (isTRUE(grepl("\\$ALTDOC_MAN_BLOCK", sidebar))) { + sidebar <- gsub("\\$ALTDOC_MAN_BLOCK", "%s", sidebar) + sidebar <- sprintf(sidebar, tmp) + } sidebar <- strsplit(sidebar, "\n")[[1]] } else { sidebar <- sidebar[!grepl("\\$ALTDOC_MAN_BLOCK", sidebar)] From 1b7596c25774957cdfdc7bf0add026f2bd844a3c Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 16:08:43 -0400 Subject: [PATCH 09/21] tryCatch --- R/autolink.R | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/R/autolink.R b/R/autolink.R index 7920476c..b96f6dcd 100644 --- a/R/autolink.R +++ b/R/autolink.R @@ -1,8 +1,13 @@ .autolink <- function(path = ".") { + # everyting wrapped in tryCatch() because especially error prone with weird pandoc memory errors html_files <- c(tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), error = function(e) NULL), tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$"), error = function(e) NULL)) for (h in html_files) { - downlit::downlit_html_path(h, h) + tmp <- try(downlit::downlit_html_path(h, h), silent = TRUE) + if (inherits(tmp, "try-error")) { + cli::cli_alert_danger(sprintf("Failed to auto-link: %s", h)) + } + } # h <- fs::path_join(c(path, "docs/index.html")) # if (fs::file_exists(h)) { @@ -13,7 +18,10 @@ tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.md$"), error = function(e) NULL), tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.md$"), error = function(e) NULL)) for (m in md_files) { - downlit::downlit_md_path(m, m) + tmp <- try(downlit::downlit_md_path(m, m), silent = TRUE) + if (inherits(tmp, "try-error")) { + cli::cli_alert_danger(sprintf("Failed to auto-link: %s", h)) + } } # m <- fs::path_join(c(path, "docs/README.md")) # if (fs::file_exists(m)) { From 96f563addd50a944a220ef78cc28750144f26a9f Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 18:39:45 -0400 Subject: [PATCH 10/21] revert parallel=TRUE --- inst/gha/altdoc.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/gha/altdoc.yaml b/inst/gha/altdoc.yaml index e0a69f7c..6b060fde 100644 --- a/inst/gha/altdoc.yaml +++ b/inst/gha/altdoc.yaml @@ -61,7 +61,7 @@ jobs: install.packages(".", repos = NULL, type = "source") install.packages("pkgload") pkgload::load_all() - altdoc::render_docs(parallel = FALSE, freeze = FALSE) + altdoc::render_docs(parallel = TRUE, freeze = FALSE) shell: Rscript {0} - name: Deploy to GitHub pages 🚀 From b8386c726069ea3536d12d21e8a89e06bc36d50b Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 19:28:35 -0400 Subject: [PATCH 11/21] .add_pkgdown() --- R/setup_docs.R | 1 + R/utils.R | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/R/setup_docs.R b/R/setup_docs.R index 43a7472c..6ca55224 100644 --- a/R/setup_docs.R +++ b/R/setup_docs.R @@ -109,6 +109,7 @@ setup_docs <- function(tool, path = ".", overwrite = FALSE) { .add_rbuildignore("^docs$", path = path) .add_rbuildignore("^altdoc$", path = path) .add_gitignore("altdoc/freeze.rds", path = path) + .add_pkgdown(path = path) if (tool == "quarto_website") { .add_rbuildignore("^_quarto$", path = path) .add_gitignore("_quarto/*", path = path) diff --git a/R/utils.R b/R/utils.R index 533c4ff3..373f4bab 100644 --- a/R/utils.R +++ b/R/utils.R @@ -127,6 +127,26 @@ } +.add_pkgdown <- function(path = ".") { + if (!isTRUE(.dir_is_package(path))) { + stop(".add_pkgdown() must be run from the root of a package.", call. = FALSE) + } + url <- desc::desc_get_urls() + fn <- fs::path_join(c(path, "altdoc/pkgdown.yml")) + if (!fs::file_exists(fn) && length(url) > 0) { + url <- url[1] + vig <- fs::path_join(c(url, "vignettes")) + man <- fs::path_join(c(url, "man")) + content <- c( + "urls:", + paste(" reference:", man), + paste(" article:", vig), + "") + cli::cli_alert_info("Adding altdoc/pkgdown.yml file.") + writeLines(content, fn) + } +} + .add_rbuildignore <- function(x = "^docs$", path = ".") { if (!isTRUE(.dir_is_package(path))) { From 1cab3a2dbb40a56e76e4a5e1bf6af7ec45369ae5 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 20:44:23 -0400 Subject: [PATCH 12/21] autolink=FALSE by default --- R/render_docs.R | 4 ++-- man/render_docs.Rd | 18 ++++++++++++++++-- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/R/render_docs.R b/R/render_docs.R index 592ad752..e00510be 100644 --- a/R/render_docs.R +++ b/R/render_docs.R @@ -7,7 +7,7 @@ #' @param verbose Logical. Print Rmarkdown or Quarto rendering output. #' @param parallel Logical. Render man pages and vignettes in parallel using the `future` framework. In addition to setting this argument to TRUE, users must define the parallelism plan in `future`. See the examples section below. #' @param freeze Logical. If TRUE and a man page or vignette has not changed since the last call to `render_docs()`, that file is skipped. File hashes are stored in `altdoc/freeze.rds`. If that file is deleted, all man pages and vignettes will be rendered anew. -#' @param autolink Logical. If TRUE use the `downlit` package to link function names and help calls from vignettes and man pages to documentation page on the web. +#' @param autolink Logical. If TRUE use the `downlit` package to link function names and help calls from vignettes and man pages to documentation page on the web. Warning: `downlit` works best in conjunction with the Quarto framework. `mkdocs` ignores `downlit` annotations altogether. `docute` and `docsify` display them properly, but the CSS styling can be affected. #' @inheritParams setup_docs #' @export #' @@ -45,7 +45,7 @@ #' render_docs(parallel = TRUE) #' #' } -render_docs <- function(path = ".", verbose = FALSE, parallel = FALSE, freeze = FALSE, autolink = TRUE) { +render_docs <- function(path = ".", verbose = FALSE, parallel = FALSE, freeze = FALSE, autolink = FALSE) { path <- .convert_path(path) tool <- .doc_type(path) diff --git a/man/render_docs.Rd b/man/render_docs.Rd index c3c84d58..fb9166b8 100644 --- a/man/render_docs.Rd +++ b/man/render_docs.Rd @@ -9,7 +9,7 @@ render_docs( verbose = FALSE, parallel = FALSE, freeze = FALSE, - autolink = TRUE + autolink = FALSE ) } \arguments{ @@ -21,7 +21,7 @@ render_docs( \item{freeze}{Logical. If TRUE and a man page or vignette has not changed since the last call to \code{render_docs()}, that file is skipped. File hashes are stored in \code{altdoc/freeze.rds}. If that file is deleted, all man pages and vignettes will be rendered anew.} -\item{autolink}{Logical. If TRUE use the \code{downlit} package to link function names and help calls from vignettes and man pages to documentation page on the web.} +\item{autolink}{Logical. If TRUE use the \code{downlit} package to link function names and help calls from vignettes and man pages to documentation page on the web. Warning: \code{downlit} works best in conjunction with the Quarto framework. \code{mkdocs} ignores \code{downlit} annotations altogether. \code{docute} and \code{docsify} display them properly, but the CSS styling can be affected.} } \description{ Render and update the function reference manual, vignettes, README, NEWS, CHANGELOG, LICENSE, @@ -90,6 +90,20 @@ The README file uses the vignette preamble. To preempt this behavior, add your own preamble to the README file or to a vignette. } +\section{Freeze}{ + + +When working on a package, running \code{render_docs()} to preview changes can be a time-consuming road block. The argument \code{freeze = TRUE} tries to improve the experience by preventing rerendering of files that have not changed since the last time \code{render_docs()} was ran. Note that changes to package internals will not cause a rerender, so rerendering the entire docs can still be necessary. + +For non-Quarto formats, this is done by creating a \code{freeze.rds} file in \verb{altdoc/} that is able to determine which documentation files have changed. + +For the Quarto format, we rely on the \href{https://quarto.org/docs/projects/code-execution.html#freeze}{Quarto freeze} feature. Freezing a document needs to be set either at a project or per-file level. Freezing a document needs to be set either at a project or per-file level. To do so, add to either \code{quarto_website.yml} or the frontmatter of a file: + +\if{html}{\out{
}}\preformatted{execute: + freeze: auto +}\if{html}{\out{
}} +} + \examples{ if (interactive()) { From 46bb490155b1da399b73a1bbd663efa214ddeb7a Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 20:51:29 -0400 Subject: [PATCH 13/21] restore tests --- tests/testthat/_snaps/docsify/render_docs.md | 556 ++++++++++--------- tests/testthat/_snaps/docute/render_docs.md | 556 ++++++++++--------- tests/testthat/_snaps/mkdocs/render_docs.md | 406 +++++++------- 3 files changed, 771 insertions(+), 747 deletions(-) diff --git a/tests/testthat/_snaps/docsify/render_docs.md b/tests/testthat/_snaps/docsify/render_docs.md index 2525afe4..85ab45aa 100644 --- a/tests/testthat/_snaps/docsify/render_docs.md +++ b/tests/testthat/_snaps/docsify/render_docs.md @@ -128,301 +128,311 @@ Code .readlines("docs/man/hello_base.md") Output - [1] "# Base function" - [2] "" - [3] "## Description" - [4] "" - [5] "Base function" - [6] "" - [7] "## Usage" - [8] "" - [9] "
hello_base(x = 2)"                                                                                                                                                                                                                                                                
-      [10] "
" - [11] "" - [12] "## Arguments" - [13] "" - [14] "" - [15] "" - [16] "" - [19] "" - [22] "" - [23] "
" - [17] "x" - [18] "" - [20] "A parameter" - [21] "
" - [24] "" - [25] "## Details" - [26] "" - [27] "Some code with weird symbols: pl$when(condition) and" - [28] "pl$then(output)" - [29] "" - [30] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" - [31] "" - [32] "## Value" - [33] "" - [34] "Some value" - [35] "" - [36] "## Examples" - [37] "" - [38] "
"                                                                                                                                                                                                                                                                                           
-      [39] "library(testpkg.altdoc)"                                                                     
-      [40] ""                                                                                                                                                                                                                                                                                                  
-      [41] "hello_base()
" - [42] "" - [43] " [1] \"Hello, world!\"" - [44] "" - [45] "
"                                                                                                                                                                                                                                                                                           
-      [46] "mtcars$drat <- mtcars$drat + 1"                                              
-      [47] "head(mtcars[[\"drat\"]], 2)
" - [48] "" - [49] " [1] 4.9 4.9" + [1] "" + [2] "" + [3] "# Base function" + [4] "" + [5] "## Description" + [6] "" + [7] "Base function" + [8] "" + [9] "## Usage" + [10] "" + [11] "
hello_base(x = 2)"                                
+      [12] "
" + [13] "" + [14] "## Arguments" + [15] "" + [16] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Details" + [28] "" + [29] "Some code with weird symbols: pl$when(condition) and" + [30] "pl$then(output)" + [31] "" + [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" + [33] "" + [34] "## Value" + [35] "" + [36] "Some value" + [37] "" + [38] "## Examples" + [39] "" + [40] "``` r" + [41] "library(testpkg.altdoc)" + [42] "" + [43] "hello_base()" + [44] "```" + [45] "" + [46] " [1] \"Hello, world!\"" + [47] "" + [48] "``` r" + [49] "mtcars$drat <- mtcars$drat + 1" + [50] "head(mtcars[[\"drat\"]], 2)" + [51] "```" + [52] "" + [53] " [1] 4.9 4.9" --- Code .readlines("docs/man/hello_r6.md") Output - [1] "# Create a \"conductor\" tour" - [2] "" - [3] "## Description" - [4] "" - [5] "blah blah blah" - [6] "" - [7] "## Methods" - [8] "" - [9] "

" - [10] "Public methods" - [11] "

" - [12] "" - [34] "
" - [35] "" - [36] "" - [37] "" - [38] "

" - [39] "Method new()" - [40] "

" - [41] "
" - [42] "Usage" - [43] "
" - [44] "" - [45] "
hello_r6\\$new()
" - [46] "" - [47] "
" - [48] "Details" - [49] "
" - [50] "" - [51] "Initialise Conductor." - [52] "" - [53] "
" - [54] "" - [55] "" - [56] "" - [57] "

" - [58] "Method init()" - [59] "

" - [60] "
" - [61] "Usage" - [62] "
" - [63] "" - [64] "
hello_r6\\$init(session = NULL)
" - [65] "" - [66] "
" - [67] "Arguments" - [68] "
" - [69] "" - [70] "
" - [71] "
" - [72] "session" - [73] "
" - [74] "
" - [75] "A valid Shiny session. If NULL (default), the function" - [76] "attempts to get the session with" - [77] "shiny::getDefaultReactiveDomain()." - [78] "
" - [79] "
" - [80] "" - [81] "
" - [82] "Details" - [83] "
" - [84] "" - [85] "Initialise Conductor." - [86] "" - [87] "
" - [88] "" - [89] "" - [90] "" - [91] "

" - [92] "Method step()" - [93] "

" - [94] "
" - [95] "Usage" - [96] "
" - [97] "" - [98] "
hello_r6\\$step(title = NULL)
" - [99] "" - [100] "
" - [101] "Arguments" - [102] "
" - [103] "" - [104] "
" - [105] "
" - [106] "title" - [107] "
" - [108] "
" - [109] "Title of the popover." - [110] "
" - [111] "
" - [112] "" - [113] "
" - [114] "Details" - [115] "
" - [116] "" - [117] "Add a step in a Conductor tour." - [118] "" - [119] "
" - [120] "" - [121] "" - [122] "" - [123] "

" - [124] "Method clone()" - [125] "

" - [126] "" - [127] "The objects of this class are cloneable with this method." - [128] "" - [129] "
" - [130] "Usage" - [131] "
" - [132] "" - [133] "
hello_r6\\$clone(deep = FALSE)
" - [134] "" - [135] "
" - [136] "Arguments" - [137] "
" - [138] "" - [139] "
" - [140] "
" - [141] "deep" - [142] "
" - [143] "
" - [144] "Whether to make a deep clone." - [145] "
" - [146] "
" + [1] "" + [2] "" + [3] "# Create a \"conductor\" tour" + [4] "" + [5] "## Description" + [6] "" + [7] "blah blah blah" + [8] "" + [9] "## Methods" + [10] "" + [11] "

" + [12] "Public methods" + [13] "

" + [14] "" + [36] "
" + [37] "" + [38] "" + [39] "" + [40] "

" + [41] "Method new()" + [42] "

" + [43] "
" + [44] "Usage" + [45] "
" + [46] "" + [47] "
hello_r6\\$new()
" + [48] "" + [49] "
" + [50] "Details" + [51] "
" + [52] "" + [53] "Initialise Conductor." + [54] "" + [55] "
" + [56] "" + [57] "" + [58] "" + [59] "

" + [60] "Method init()" + [61] "

" + [62] "
" + [63] "Usage" + [64] "
" + [65] "" + [66] "
hello_r6\\$init(session = NULL)
" + [67] "" + [68] "
" + [69] "Arguments" + [70] "
" + [71] "" + [72] "
" + [73] "
" + [74] "session" + [75] "
" + [76] "
" + [77] "A valid Shiny session. If NULL (default), the function" + [78] "attempts to get the session with" + [79] "shiny::getDefaultReactiveDomain()." + [80] "
" + [81] "
" + [82] "" + [83] "
" + [84] "Details" + [85] "
" + [86] "" + [87] "Initialise Conductor." + [88] "" + [89] "
" + [90] "" + [91] "" + [92] "" + [93] "

" + [94] "Method step()" + [95] "

" + [96] "
" + [97] "Usage" + [98] "
" + [99] "" + [100] "
hello_r6\\$step(title = NULL)
" + [101] "" + [102] "
" + [103] "Arguments" + [104] "
" + [105] "" + [106] "
" + [107] "
" + [108] "title" + [109] "
" + [110] "
" + [111] "Title of the popover." + [112] "
" + [113] "
" + [114] "" + [115] "
" + [116] "Details" + [117] "
" + [118] "" + [119] "Add a step in a Conductor tour." + [120] "" + [121] "
" + [122] "" + [123] "" + [124] "" + [125] "

" + [126] "Method clone()" + [127] "

" + [128] "" + [129] "The objects of this class are cloneable with this method." + [130] "" + [131] "
" + [132] "Usage" + [133] "
" + [134] "" + [135] "
hello_r6\\$clone(deep = FALSE)
" + [136] "" + [137] "
" + [138] "Arguments" + [139] "
" + [140] "" + [141] "
" + [142] "
" + [143] "deep" + [144] "
" + [145] "
" + [146] "Whether to make a deep clone." + [147] "
" + [148] "
" --- Code .readlines("docs/man/examplesIf_true.md") Output - [1] "# Examples If TRUE" - [2] "" - [3] "## Description" - [4] "" - [5] "Examples If TRUE" - [6] "" - [7] "## Usage" - [8] "" - [9] "
examplesIf_true()"                                                                                                                                                                                           
-      [10] "
" - [11] "" - [12] "## Arguments" - [13] "" - [14] "" - [15] "" - [16] "" - [19] "" - [22] "" - [23] "
" - [17] "x" - [18] "" - [20] "A parameter" - [21] "
" - [24] "" - [25] "## Value" - [26] "" - [27] "Some value" - [28] "" - [29] "## Examples" - [30] "" - [31] "
"                                                                                                                                                                                                                      
-      [32] "library(testpkg.altdoc)"
-      [33] ""                                                                                                                                                                                                                             
-      [34] ""                                                                                                                                                                                                                             
-      [35] "examplesIf_true()
" - [36] "" - [37] " [1] \"Hello, world!\"" + [1] "" + [2] "" + [3] "# Examples If TRUE" + [4] "" + [5] "## Description" + [6] "" + [7] "Examples If TRUE" + [8] "" + [9] "## Usage" + [10] "" + [11] "
examplesIf_true()"                                
+      [12] "
" + [13] "" + [14] "## Arguments" + [15] "" + [16] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Value" + [28] "" + [29] "Some value" + [30] "" + [31] "## Examples" + [32] "" + [33] "``` r" + [34] "library(testpkg.altdoc)" + [35] "" + [36] "" + [37] "examplesIf_true()" + [38] "```" + [39] "" + [40] " [1] \"Hello, world!\"" --- Code .readlines("docs/man/examplesIf_false.md") Output - [1] "# Examples If FALSE" - [2] "" - [3] "## Description" - [4] "" - [5] "Examples If FALSE" - [6] "" - [7] "## Usage" - [8] "" - [9] "
examplesIf_false()"                                                                                                                                                                                          
-      [10] "
" - [11] "" - [12] "## Arguments" - [13] "" - [14] "" - [15] "" - [16] "" - [19] "" - [22] "" - [23] "
" - [17] "x" - [18] "" - [20] "A parameter" - [21] "
" - [24] "" - [25] "## Value" - [26] "" - [27] "Some value" - [28] "" - [29] "## Examples" - [30] "" - [31] "
"                                                                                                                                                                                                                      
-      [32] "library(testpkg.altdoc)"
-      [33] ""                                                                                                                                                                                                                             
-      [34] ""                                                                                                                                                                                                                             
-      [35] "examplesIf_false()
" + [1] "" + [2] "" + [3] "# Examples If FALSE" + [4] "" + [5] "## Description" + [6] "" + [7] "Examples If FALSE" + [8] "" + [9] "## Usage" + [10] "" + [11] "
examplesIf_false()"                               
+      [12] "
" + [13] "" + [14] "## Arguments" + [15] "" + [16] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Value" + [28] "" + [29] "Some value" + [30] "" + [31] "## Examples" + [32] "" + [33] "``` r" + [34] "library(testpkg.altdoc)" + [35] "" + [36] "" + [37] "examplesIf_false()" + [38] "```" --- Code .readlines("docs/vignettes/test.md") Output - [1] "# test" - [2] "" - [3] "
"                                                                                                                                                                                                                            
-      [4] "library(testpkg.altdoc)
" - [5] "" - [6] "hello there" + [1] "# test" "" + [3] "" "``` r" + [5] "library(testpkg.altdoc)" "```" + [7] "" "hello there" diff --git a/tests/testthat/_snaps/docute/render_docs.md b/tests/testthat/_snaps/docute/render_docs.md index 6da044bb..8aba0fef 100644 --- a/tests/testthat/_snaps/docute/render_docs.md +++ b/tests/testthat/_snaps/docute/render_docs.md @@ -119,301 +119,311 @@ Code .readlines("docs/man/hello_base.md") Output - [1] "# Base function" - [2] "" - [3] "## Description" - [4] "" - [5] "Base function" - [6] "" - [7] "## Usage" - [8] "" - [9] "
hello_base(x = 2)"                                                                                                                                                                                                                                                                
-      [10] "
" - [11] "" - [12] "## Arguments" - [13] "" - [14] "" - [15] "" - [16] "" - [19] "" - [22] "" - [23] "
" - [17] "x" - [18] "" - [20] "A parameter" - [21] "
" - [24] "" - [25] "## Details" - [26] "" - [27] "Some code with weird symbols: pl$when(condition) and" - [28] "pl$then(output)" - [29] "" - [30] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" - [31] "" - [32] "## Value" - [33] "" - [34] "Some value" - [35] "" - [36] "## Examples" - [37] "" - [38] "
"                                                                                                                                                                                                                                                                                           
-      [39] "library(testpkg.altdoc)"                                                                     
-      [40] ""                                                                                                                                                                                                                                                                                                  
-      [41] "hello_base()
" - [42] "" - [43] " [1] \"Hello, world!\"" - [44] "" - [45] "
"                                                                                                                                                                                                                                                                                           
-      [46] "mtcars$drat <- mtcars$drat + 1"                                              
-      [47] "head(mtcars[[\"drat\"]], 2)
" - [48] "" - [49] " [1] 4.9 4.9" + [1] "" + [2] "" + [3] "# Base function" + [4] "" + [5] "## Description" + [6] "" + [7] "Base function" + [8] "" + [9] "## Usage" + [10] "" + [11] "
hello_base(x = 2)"                                
+      [12] "
" + [13] "" + [14] "## Arguments" + [15] "" + [16] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Details" + [28] "" + [29] "Some code with weird symbols: pl$when(condition) and" + [30] "pl$then(output)" + [31] "" + [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" + [33] "" + [34] "## Value" + [35] "" + [36] "Some value" + [37] "" + [38] "## Examples" + [39] "" + [40] "``` r" + [41] "library(testpkg.altdoc)" + [42] "" + [43] "hello_base()" + [44] "```" + [45] "" + [46] " [1] \"Hello, world!\"" + [47] "" + [48] "``` r" + [49] "mtcars$drat <- mtcars$drat + 1" + [50] "head(mtcars[[\"drat\"]], 2)" + [51] "```" + [52] "" + [53] " [1] 4.9 4.9" --- Code .readlines("docs/man/hello_r6.md") Output - [1] "# Create a \"conductor\" tour" - [2] "" - [3] "## Description" - [4] "" - [5] "blah blah blah" - [6] "" - [7] "## Methods" - [8] "" - [9] "

" - [10] "Public methods" - [11] "

" - [12] "" - [34] "
" - [35] "" - [36] "" - [37] "" - [38] "

" - [39] "Method new()" - [40] "

" - [41] "
" - [42] "Usage" - [43] "
" - [44] "" - [45] "
hello_r6\\$new()
" - [46] "" - [47] "
" - [48] "Details" - [49] "
" - [50] "" - [51] "Initialise Conductor." - [52] "" - [53] "
" - [54] "" - [55] "" - [56] "" - [57] "

" - [58] "Method init()" - [59] "

" - [60] "
" - [61] "Usage" - [62] "
" - [63] "" - [64] "
hello_r6\\$init(session = NULL)
" - [65] "" - [66] "
" - [67] "Arguments" - [68] "
" - [69] "" - [70] "
" - [71] "
" - [72] "session" - [73] "
" - [74] "
" - [75] "A valid Shiny session. If NULL (default), the function" - [76] "attempts to get the session with" - [77] "shiny::getDefaultReactiveDomain()." - [78] "
" - [79] "
" - [80] "" - [81] "
" - [82] "Details" - [83] "
" - [84] "" - [85] "Initialise Conductor." - [86] "" - [87] "
" - [88] "" - [89] "" - [90] "" - [91] "

" - [92] "Method step()" - [93] "

" - [94] "
" - [95] "Usage" - [96] "
" - [97] "" - [98] "
hello_r6\\$step(title = NULL)
" - [99] "" - [100] "
" - [101] "Arguments" - [102] "
" - [103] "" - [104] "
" - [105] "
" - [106] "title" - [107] "
" - [108] "
" - [109] "Title of the popover." - [110] "
" - [111] "
" - [112] "" - [113] "
" - [114] "Details" - [115] "
" - [116] "" - [117] "Add a step in a Conductor tour." - [118] "" - [119] "
" - [120] "" - [121] "" - [122] "" - [123] "

" - [124] "Method clone()" - [125] "

" - [126] "" - [127] "The objects of this class are cloneable with this method." - [128] "" - [129] "
" - [130] "Usage" - [131] "
" - [132] "" - [133] "
hello_r6\\$clone(deep = FALSE)
" - [134] "" - [135] "
" - [136] "Arguments" - [137] "
" - [138] "" - [139] "
" - [140] "
" - [141] "deep" - [142] "
" - [143] "
" - [144] "Whether to make a deep clone." - [145] "
" - [146] "
" + [1] "" + [2] "" + [3] "# Create a \"conductor\" tour" + [4] "" + [5] "## Description" + [6] "" + [7] "blah blah blah" + [8] "" + [9] "## Methods" + [10] "" + [11] "

" + [12] "Public methods" + [13] "

" + [14] "" + [36] "
" + [37] "" + [38] "" + [39] "" + [40] "

" + [41] "Method new()" + [42] "

" + [43] "
" + [44] "Usage" + [45] "
" + [46] "" + [47] "
hello_r6\\$new()
" + [48] "" + [49] "
" + [50] "Details" + [51] "
" + [52] "" + [53] "Initialise Conductor." + [54] "" + [55] "
" + [56] "" + [57] "" + [58] "" + [59] "

" + [60] "Method init()" + [61] "

" + [62] "
" + [63] "Usage" + [64] "
" + [65] "" + [66] "
hello_r6\\$init(session = NULL)
" + [67] "" + [68] "
" + [69] "Arguments" + [70] "
" + [71] "" + [72] "
" + [73] "
" + [74] "session" + [75] "
" + [76] "
" + [77] "A valid Shiny session. If NULL (default), the function" + [78] "attempts to get the session with" + [79] "shiny::getDefaultReactiveDomain()." + [80] "
" + [81] "
" + [82] "" + [83] "
" + [84] "Details" + [85] "
" + [86] "" + [87] "Initialise Conductor." + [88] "" + [89] "
" + [90] "" + [91] "" + [92] "" + [93] "

" + [94] "Method step()" + [95] "

" + [96] "
" + [97] "Usage" + [98] "
" + [99] "" + [100] "
hello_r6\\$step(title = NULL)
" + [101] "" + [102] "
" + [103] "Arguments" + [104] "
" + [105] "" + [106] "
" + [107] "
" + [108] "title" + [109] "
" + [110] "
" + [111] "Title of the popover." + [112] "
" + [113] "
" + [114] "" + [115] "
" + [116] "Details" + [117] "
" + [118] "" + [119] "Add a step in a Conductor tour." + [120] "" + [121] "
" + [122] "" + [123] "" + [124] "" + [125] "

" + [126] "Method clone()" + [127] "

" + [128] "" + [129] "The objects of this class are cloneable with this method." + [130] "" + [131] "
" + [132] "Usage" + [133] "
" + [134] "" + [135] "
hello_r6\\$clone(deep = FALSE)
" + [136] "" + [137] "
" + [138] "Arguments" + [139] "
" + [140] "" + [141] "
" + [142] "
" + [143] "deep" + [144] "
" + [145] "
" + [146] "Whether to make a deep clone." + [147] "
" + [148] "
" --- Code .readlines("docs/man/examplesIf_true.md") Output - [1] "# Examples If TRUE" - [2] "" - [3] "## Description" - [4] "" - [5] "Examples If TRUE" - [6] "" - [7] "## Usage" - [8] "" - [9] "
examplesIf_true()"                                                                                                                                                                                           
-      [10] "
" - [11] "" - [12] "## Arguments" - [13] "" - [14] "" - [15] "" - [16] "" - [19] "" - [22] "" - [23] "
" - [17] "x" - [18] "" - [20] "A parameter" - [21] "
" - [24] "" - [25] "## Value" - [26] "" - [27] "Some value" - [28] "" - [29] "## Examples" - [30] "" - [31] "
"                                                                                                                                                                                                                      
-      [32] "library(testpkg.altdoc)"
-      [33] ""                                                                                                                                                                                                                             
-      [34] ""                                                                                                                                                                                                                             
-      [35] "examplesIf_true()
" - [36] "" - [37] " [1] \"Hello, world!\"" + [1] "" + [2] "" + [3] "# Examples If TRUE" + [4] "" + [5] "## Description" + [6] "" + [7] "Examples If TRUE" + [8] "" + [9] "## Usage" + [10] "" + [11] "
examplesIf_true()"                                
+      [12] "
" + [13] "" + [14] "## Arguments" + [15] "" + [16] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Value" + [28] "" + [29] "Some value" + [30] "" + [31] "## Examples" + [32] "" + [33] "``` r" + [34] "library(testpkg.altdoc)" + [35] "" + [36] "" + [37] "examplesIf_true()" + [38] "```" + [39] "" + [40] " [1] \"Hello, world!\"" --- Code .readlines("docs/man/examplesIf_false.md") Output - [1] "# Examples If FALSE" - [2] "" - [3] "## Description" - [4] "" - [5] "Examples If FALSE" - [6] "" - [7] "## Usage" - [8] "" - [9] "
examplesIf_false()"                                                                                                                                                                                          
-      [10] "
" - [11] "" - [12] "## Arguments" - [13] "" - [14] "" - [15] "" - [16] "" - [19] "" - [22] "" - [23] "
" - [17] "x" - [18] "" - [20] "A parameter" - [21] "
" - [24] "" - [25] "## Value" - [26] "" - [27] "Some value" - [28] "" - [29] "## Examples" - [30] "" - [31] "
"                                                                                                                                                                                                                      
-      [32] "library(testpkg.altdoc)"
-      [33] ""                                                                                                                                                                                                                             
-      [34] ""                                                                                                                                                                                                                             
-      [35] "examplesIf_false()
" + [1] "" + [2] "" + [3] "# Examples If FALSE" + [4] "" + [5] "## Description" + [6] "" + [7] "Examples If FALSE" + [8] "" + [9] "## Usage" + [10] "" + [11] "
examplesIf_false()"                               
+      [12] "
" + [13] "" + [14] "## Arguments" + [15] "" + [16] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Value" + [28] "" + [29] "Some value" + [30] "" + [31] "## Examples" + [32] "" + [33] "``` r" + [34] "library(testpkg.altdoc)" + [35] "" + [36] "" + [37] "examplesIf_false()" + [38] "```" --- Code .readlines("docs/vignettes/test.md") Output - [1] "# test" - [2] "" - [3] "
"                                                                                                                                                                                                                            
-      [4] "library(testpkg.altdoc)
" - [5] "" - [6] "hello there" + [1] "# test" "" + [3] "" "``` r" + [5] "library(testpkg.altdoc)" "```" + [7] "" "hello there" diff --git a/tests/testthat/_snaps/mkdocs/render_docs.md b/tests/testthat/_snaps/mkdocs/render_docs.md index b1d81470..b7fb2385 100644 --- a/tests/testthat/_snaps/mkdocs/render_docs.md +++ b/tests/testthat/_snaps/mkdocs/render_docs.md @@ -18,217 +18,221 @@ Code .readlines("docs/man/hello_base.md") Output - [1] "# Base function" - [2] "" - [3] "## Description" - [4] "" - [5] "Base function" - [6] "" - [7] "## Usage" - [8] "" - [9] "
hello_base(x = 2)"                                                                                                                                                                                                                                                                
-      [10] "
" - [11] "" - [12] "## Arguments" - [13] "" - [14] "" - [15] "" - [16] "" - [19] "" - [22] "" - [23] "
" - [17] "x" - [18] "" - [20] "A parameter" - [21] "
" - [24] "" - [25] "## Details" - [26] "" - [27] "Some code with weird symbols: pl$when(condition) and" - [28] "pl$then(output)" - [29] "" - [30] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" - [31] "" - [32] "## Value" - [33] "" - [34] "Some value" - [35] "" - [36] "## Examples" - [37] "" - [38] "
"                                                                                                                                                                                                                                                                                           
-      [39] "library(testpkg.altdoc)"                                                                     
-      [40] ""                                                                                                                                                                                                                                                                                                  
-      [41] "hello_base()
" - [42] "" - [43] " [1] \"Hello, world!\"" - [44] "" - [45] "
"                                                                                                                                                                                                                                                                                           
-      [46] "mtcars$drat <- mtcars$drat + 1"                                              
-      [47] "head(mtcars[[\"drat\"]], 2)
" - [48] "" - [49] " [1] 4.9 4.9" + [1] "" + [2] "" + [3] "# Base function" + [4] "" + [5] "## Description" + [6] "" + [7] "Base function" + [8] "" + [9] "## Usage" + [10] "" + [11] "
hello_base(x = 2)"                                
+      [12] "
" + [13] "" + [14] "## Arguments" + [15] "" + [16] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Details" + [28] "" + [29] "Some code with weird symbols: pl$when(condition) and" + [30] "pl$then(output)" + [31] "" + [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2" + [33] "" + [34] "## Value" + [35] "" + [36] "Some value" + [37] "" + [38] "## Examples" + [39] "" + [40] "``` r" + [41] "library(testpkg.altdoc)" + [42] "" + [43] "hello_base()" + [44] "```" + [45] "" + [46] " [1] \"Hello, world!\"" + [47] "" + [48] "``` r" + [49] "mtcars$drat <- mtcars$drat + 1" + [50] "head(mtcars[[\"drat\"]], 2)" + [51] "```" + [52] "" + [53] " [1] 4.9 4.9" --- Code .readlines("docs/man/hello_r6.md") Output - [1] "# Create a \"conductor\" tour" - [2] "" - [3] "## Description" - [4] "" - [5] "blah blah blah" - [6] "" - [7] "## Methods" - [8] "" - [9] "

" - [10] "Public methods" - [11] "

" - [12] "" - [34] "
" - [35] "" - [36] "" - [37] "" - [38] "

" - [39] "Method new()" - [40] "

" - [41] "
" - [42] "Usage" - [43] "
" - [44] "" - [45] "
hello_r6\\$new()
" - [46] "" - [47] "
" - [48] "Details" - [49] "
" - [50] "" - [51] "Initialise Conductor." - [52] "" - [53] "
" - [54] "" - [55] "" - [56] "" - [57] "

" - [58] "Method init()" - [59] "

" - [60] "
" - [61] "Usage" - [62] "
" - [63] "" - [64] "
hello_r6\\$init(session = NULL)
" - [65] "" - [66] "
" - [67] "Arguments" - [68] "
" - [69] "" - [70] "
" - [71] "
" - [72] "session" - [73] "
" - [74] "
" - [75] "A valid Shiny session. If NULL (default), the function" - [76] "attempts to get the session with" - [77] "shiny::getDefaultReactiveDomain()." - [78] "
" - [79] "
" - [80] "" - [81] "
" - [82] "Details" - [83] "
" - [84] "" - [85] "Initialise Conductor." - [86] "" - [87] "
" - [88] "" - [89] "" - [90] "" - [91] "

" - [92] "Method step()" - [93] "

" - [94] "
" - [95] "Usage" - [96] "
" - [97] "" - [98] "
hello_r6\\$step(title = NULL)
" - [99] "" - [100] "
" - [101] "Arguments" - [102] "
" - [103] "" - [104] "
" - [105] "
" - [106] "title" - [107] "
" - [108] "
" - [109] "Title of the popover." - [110] "
" - [111] "
" - [112] "" - [113] "
" - [114] "Details" - [115] "
" - [116] "" - [117] "Add a step in a Conductor tour." - [118] "" - [119] "
" - [120] "" - [121] "" - [122] "" - [123] "

" - [124] "Method clone()" - [125] "

" - [126] "" - [127] "The objects of this class are cloneable with this method." - [128] "" - [129] "
" - [130] "Usage" - [131] "
" - [132] "" - [133] "
hello_r6\\$clone(deep = FALSE)
" - [134] "" - [135] "
" - [136] "Arguments" - [137] "
" - [138] "" - [139] "
" - [140] "
" - [141] "deep" - [142] "
" - [143] "
" - [144] "Whether to make a deep clone." - [145] "
" - [146] "
" + [1] "" + [2] "" + [3] "# Create a \"conductor\" tour" + [4] "" + [5] "## Description" + [6] "" + [7] "blah blah blah" + [8] "" + [9] "## Methods" + [10] "" + [11] "

" + [12] "Public methods" + [13] "

" + [14] "" + [36] "
" + [37] "" + [38] "" + [39] "" + [40] "

" + [41] "Method new()" + [42] "

" + [43] "
" + [44] "Usage" + [45] "
" + [46] "" + [47] "
hello_r6\\$new()
" + [48] "" + [49] "
" + [50] "Details" + [51] "
" + [52] "" + [53] "Initialise Conductor." + [54] "" + [55] "
" + [56] "" + [57] "" + [58] "" + [59] "

" + [60] "Method init()" + [61] "

" + [62] "
" + [63] "Usage" + [64] "
" + [65] "" + [66] "
hello_r6\\$init(session = NULL)
" + [67] "" + [68] "
" + [69] "Arguments" + [70] "
" + [71] "" + [72] "
" + [73] "
" + [74] "session" + [75] "
" + [76] "
" + [77] "A valid Shiny session. If NULL (default), the function" + [78] "attempts to get the session with" + [79] "shiny::getDefaultReactiveDomain()." + [80] "
" + [81] "
" + [82] "" + [83] "
" + [84] "Details" + [85] "
" + [86] "" + [87] "Initialise Conductor." + [88] "" + [89] "
" + [90] "" + [91] "" + [92] "" + [93] "

" + [94] "Method step()" + [95] "

" + [96] "
" + [97] "Usage" + [98] "
" + [99] "" + [100] "
hello_r6\\$step(title = NULL)
" + [101] "" + [102] "
" + [103] "Arguments" + [104] "
" + [105] "" + [106] "
" + [107] "
" + [108] "title" + [109] "
" + [110] "
" + [111] "Title of the popover." + [112] "
" + [113] "
" + [114] "" + [115] "
" + [116] "Details" + [117] "
" + [118] "" + [119] "Add a step in a Conductor tour." + [120] "" + [121] "
" + [122] "" + [123] "" + [124] "" + [125] "

" + [126] "Method clone()" + [127] "

" + [128] "" + [129] "The objects of this class are cloneable with this method." + [130] "" + [131] "
" + [132] "Usage" + [133] "
" + [134] "" + [135] "
hello_r6\\$clone(deep = FALSE)
" + [136] "" + [137] "
" + [138] "Arguments" + [139] "
" + [140] "" + [141] "
" + [142] "
" + [143] "deep" + [144] "
" + [145] "
" + [146] "Whether to make a deep clone." + [147] "
" + [148] "
" --- Code .readlines("docs/vignettes/test.md") Output - [1] "# test" - [2] "" - [3] "
"                                                                                                                                                                                                                            
-      [4] "library(testpkg.altdoc)
" - [5] "" - [6] "hello there" + [1] "# test" "" + [3] "" "``` r" + [5] "library(testpkg.altdoc)" "```" + [7] "" "hello there" From fbb6b3dc8acad398fa9b2345ad21b155e5f2bd73 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 21:03:53 -0400 Subject: [PATCH 14/21] test quarto autolink --- tests/testthat/test-render_docs.R | 33 +++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/tests/testthat/test-render_docs.R b/tests/testthat/test-render_docs.R index 2929ab9c..81aae481 100644 --- a/tests/testthat/test-render_docs.R +++ b/tests/testthat/test-render_docs.R @@ -139,6 +139,39 @@ test_that("quarto: no error for basic workflow", { }) +test_that("quarto: autolink", { + skip_on_cran() + skip_if(.is_windows() && .on_ci(), "Windows on CI") + + ### setup: create a temp package using the structure of testpkg.altdoc + path_to_example_pkg <- fs::path_abs(test_path("examples/testpkg.altdoc")) + create_local_project() + fs::dir_delete("R") + fs::dir_copy(path_to_example_pkg, ".") + all_files <- list.files("testpkg.altdoc", full.names = TRUE) + for (i in all_files) { + fs::file_move(i, ".") + } + fs::dir_delete("testpkg.altdoc") + + ### generate docs + install.packages(".", repos = NULL, type = "source") + fs::file_move("README.Rmd", "README.qmd") # special thing quarto + setup_docs("quarto_website") + expect_no_error(render_docs(verbose = .on_ci(), autolink = TRUE)) + + ### Quarto output changes depending on the version, I don't have a solution for + ### now. + + ### test + # expect_snapshot(.readlines("docs/index.html")) + # expect_snapshot(.readlines("docs/NEWS.html")) + # expect_snapshot(.readlines("docs/man/hello_base.html")) + # expect_snapshot(.readlines("docs/man/hello_r6.html")) + # expect_snapshot(.readlines("docs/vignettes/test.html")) +}) + + # Test failures ------------------------------ test_that("render_docs errors if vignettes fail", { From 50d0889cd881469ef0ab6031558e733e7e6e0613 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 7 Apr 2024 21:24:39 -0400 Subject: [PATCH 15/21] docs --- R/render_docs.R | 3 ++- man-roxygen/altdoc_autolink.R | 9 +++++++++ man/render_docs.Rd | 14 +++++++++++++- 3 files changed, 24 insertions(+), 2 deletions(-) create mode 100644 man-roxygen/altdoc_autolink.R diff --git a/R/render_docs.R b/R/render_docs.R index e00510be..b250a8ed 100644 --- a/R/render_docs.R +++ b/R/render_docs.R @@ -7,7 +7,7 @@ #' @param verbose Logical. Print Rmarkdown or Quarto rendering output. #' @param parallel Logical. Render man pages and vignettes in parallel using the `future` framework. In addition to setting this argument to TRUE, users must define the parallelism plan in `future`. See the examples section below. #' @param freeze Logical. If TRUE and a man page or vignette has not changed since the last call to `render_docs()`, that file is skipped. File hashes are stored in `altdoc/freeze.rds`. If that file is deleted, all man pages and vignettes will be rendered anew. -#' @param autolink Logical. If TRUE use the `downlit` package to link function names and help calls from vignettes and man pages to documentation page on the web. Warning: `downlit` works best in conjunction with the Quarto framework. `mkdocs` ignores `downlit` annotations altogether. `docute` and `docsify` display them properly, but the CSS styling can be affected. +#' @param autolink Logical. TRUE to link function names and calls to web-based documentation. See the Autolink section below for details. #' @inheritParams setup_docs #' @export #' @@ -33,6 +33,7 @@ #' @template altdoc_variables #' @template altdoc_preambles #' @template altdoc_freeze +#' @template altdoc_autolink #' #' @examples #' if (interactive()) { diff --git a/man-roxygen/altdoc_autolink.R b/man-roxygen/altdoc_autolink.R new file mode 100644 index 00000000..07075495 --- /dev/null +++ b/man-roxygen/altdoc_autolink.R @@ -0,0 +1,9 @@ +#' @section Auto-link: +#' +#' When the `autolink` argument is `TRUE`, `altdoc` will use the `downlit` package to replace the function names on the package website by links to web-based package documentation. This works for base R libraries and any package published on CRAN. +#' +#' To allow internal links to functions documented by `altdoc`, we need to include links to correct URLs in the `altdoc/pkgdown.yml` file. By default, this file is populated with links to the first URL in the `DESCRIPTION`. When calling `render_docs(autolink=TRUE)`, the `pkgdown.yml` file is moved to the root of the website. +#' +#' Importantly, `downlit` requires the `pkgdown.yml` to be live on the website to create links. This means that links will generally not be updated when making purely local changes. Also, links may not be updated the first time an `altdoc` website is published to the web. +#' +#' Note that the `autolink` argument works best for Quarto-based websites. `mkdocs` appears to ignore `downlit` annotations altogether. `docute` and `docsify` display `downlit` annotations, but CSS styling and code highlighting sometimes suffer. diff --git a/man/render_docs.Rd b/man/render_docs.Rd index fb9166b8..ce2351cc 100644 --- a/man/render_docs.Rd +++ b/man/render_docs.Rd @@ -21,7 +21,7 @@ render_docs( \item{freeze}{Logical. If TRUE and a man page or vignette has not changed since the last call to \code{render_docs()}, that file is skipped. File hashes are stored in \code{altdoc/freeze.rds}. If that file is deleted, all man pages and vignettes will be rendered anew.} -\item{autolink}{Logical. If TRUE use the \code{downlit} package to link function names and help calls from vignettes and man pages to documentation page on the web. Warning: \code{downlit} works best in conjunction with the Quarto framework. \code{mkdocs} ignores \code{downlit} annotations altogether. \code{docute} and \code{docsify} display them properly, but the CSS styling can be affected.} +\item{autolink}{Logical. TRUE to link function names and calls to web-based documentation. See the Autolink section below for details.} } \description{ Render and update the function reference manual, vignettes, README, NEWS, CHANGELOG, LICENSE, @@ -104,6 +104,18 @@ For the Quarto format, we rely on the \href{https://quarto.org/docs/projects/cod }\if{html}{\out{}} } +\section{Auto-link}{ + + +When the \code{autolink} argument is \code{TRUE}, \code{altdoc} will use the \code{downlit} package to replace the function names on the package website by links to web-based package documentation. This works for base R libraries and any package published on CRAN. + +To allow internal links to functions documented by \code{altdoc}, we need to include links to correct URLs in the \code{altdoc/pkgdown.yml} file. By default, this file is populated with links to the first URL in the \code{DESCRIPTION}. When calling \code{render_docs(autolink=TRUE)}, the \code{pkgdown.yml} file is moved to the root of the website. + +Importantly, \code{downlit} requires the \code{pkgdown.yml} to be live on the website to create links. This means that links will generally not be updated when making purely local changes. Also, links may not be updated the first time an \code{altdoc} website is published to the web. + +Note that the \code{autolink} argument works best for Quarto-based websites. \code{mkdocs} appears to ignore \code{downlit} annotations altogether. \code{docute} and \code{docsify} display \code{downlit} annotations, but CSS styling and code highlighting sometimes suffer. +} + \examples{ if (interactive()) { From 891be48e5c65a0dec6231b11a950ed76a28094a5 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Mon, 8 Apr 2024 07:11:08 -0400 Subject: [PATCH 16/21] Update R/autolink.R Co-authored-by: Etienne Bacher <52219252+etiennebacher@users.noreply.github.com> --- R/autolink.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/autolink.R b/R/autolink.R index b96f6dcd..f2dea99a 100644 --- a/R/autolink.R +++ b/R/autolink.R @@ -1,5 +1,5 @@ .autolink <- function(path = ".") { - # everyting wrapped in tryCatch() because especially error prone with weird pandoc memory errors + # everything wrapped in tryCatch() because especially error prone with weird pandoc memory errors html_files <- c(tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), error = function(e) NULL), tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$"), error = function(e) NULL)) for (h in html_files) { From f2a5bdf69b631ed26b29edb18e001c2d521dc6f2 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Mon, 8 Apr 2024 07:14:57 -0400 Subject: [PATCH 17/21] Update R/autolink.R Co-authored-by: Etienne Bacher <52219252+etiennebacher@users.noreply.github.com> --- R/autolink.R | 4 ---- 1 file changed, 4 deletions(-) diff --git a/R/autolink.R b/R/autolink.R index f2dea99a..c36139d7 100644 --- a/R/autolink.R +++ b/R/autolink.R @@ -9,10 +9,6 @@ } } - # h <- fs::path_join(c(path, "docs/index.html")) - # if (fs::file_exists(h)) { - # downlit::downlit_html_path(h, h) - # } md_files <- c( tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.md$"), error = function(e) NULL), From bdd2c9b6ab9cef2a276c7628b7db85b008be75a8 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Mon, 8 Apr 2024 07:15:53 -0400 Subject: [PATCH 18/21] Update R/autolink.R Co-authored-by: Etienne Bacher <52219252+etiennebacher@users.noreply.github.com> --- R/autolink.R | 4 ---- 1 file changed, 4 deletions(-) diff --git a/R/autolink.R b/R/autolink.R index c36139d7..7e0a5e9b 100644 --- a/R/autolink.R +++ b/R/autolink.R @@ -19,8 +19,4 @@ cli::cli_alert_danger(sprintf("Failed to auto-link: %s", h)) } } - # m <- fs::path_join(c(path, "docs/README.md")) - # if (fs::file_exists(m)) { - # downlit::downlit_html_path(m, m) - # } } From 4a75c2b4afacacc75013bd5421389ab78c3dd7cc Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Mon, 8 Apr 2024 07:22:19 -0400 Subject: [PATCH 19/21] downlit: code review 1 --- R/autolink.R | 10 +++++----- R/utils.R | 2 +- inst/gha/altdoc.yaml | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/R/autolink.R b/R/autolink.R index 7e0a5e9b..75ccbf39 100644 --- a/R/autolink.R +++ b/R/autolink.R @@ -1,18 +1,18 @@ .autolink <- function(path = ".") { # everything wrapped in tryCatch() because especially error prone with weird pandoc memory errors - html_files <- c(tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$"), error = function(e) NULL), - tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$"), error = function(e) NULL)) + html_files <- c( + fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$", fail = FALSE), + fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$", fail = FALSE)) for (h in html_files) { tmp <- try(downlit::downlit_html_path(h, h), silent = TRUE) if (inherits(tmp, "try-error")) { cli::cli_alert_danger(sprintf("Failed to auto-link: %s", h)) } - } md_files <- c( - tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.md$"), error = function(e) NULL), - tryCatch(fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.md$"), error = function(e) NULL)) + fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.md$", fail = FALSE), + fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.md$", fail = FALSE)) for (m in md_files) { tmp <- try(downlit::downlit_md_path(m, m), silent = TRUE) if (inherits(tmp, "try-error")) { diff --git a/R/utils.R b/R/utils.R index 373f4bab..5e9543a1 100644 --- a/R/utils.R +++ b/R/utils.R @@ -131,7 +131,7 @@ if (!isTRUE(.dir_is_package(path))) { stop(".add_pkgdown() must be run from the root of a package.", call. = FALSE) } - url <- desc::desc_get_urls() + url <- setdiff(desc::desc_get_urls(), .gh_url(path)) fn <- fs::path_join(c(path, "altdoc/pkgdown.yml")) if (!fs::file_exists(fn) && length(url) > 0) { url <- url[1] diff --git a/inst/gha/altdoc.yaml b/inst/gha/altdoc.yaml index 6b060fde..e0a69f7c 100644 --- a/inst/gha/altdoc.yaml +++ b/inst/gha/altdoc.yaml @@ -61,7 +61,7 @@ jobs: install.packages(".", repos = NULL, type = "source") install.packages("pkgload") pkgload::load_all() - altdoc::render_docs(parallel = TRUE, freeze = FALSE) + altdoc::render_docs(parallel = FALSE, freeze = FALSE) shell: Rscript {0} - name: Deploy to GitHub pages 🚀 From abf7a18947f5a7b7526609630be7c67f6aaa1d3c Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Mon, 8 Apr 2024 07:30:12 -0400 Subject: [PATCH 20/21] test autolink --- tests/testthat/test-render_docs.R | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/tests/testthat/test-render_docs.R b/tests/testthat/test-render_docs.R index 81aae481..450ca235 100644 --- a/tests/testthat/test-render_docs.R +++ b/tests/testthat/test-render_docs.R @@ -160,15 +160,8 @@ test_that("quarto: autolink", { setup_docs("quarto_website") expect_no_error(render_docs(verbose = .on_ci(), autolink = TRUE)) - ### Quarto output changes depending on the version, I don't have a solution for - ### now. - - ### test - # expect_snapshot(.readlines("docs/index.html")) - # expect_snapshot(.readlines("docs/NEWS.html")) - # expect_snapshot(.readlines("docs/man/hello_base.html")) - # expect_snapshot(.readlines("docs/man/hello_r6.html")) - # expect_snapshot(.readlines("docs/vignettes/test.html")) + tmp <- .readlines("docs/vignettes/test.html") + expect_true(any(grepl("https://rdrr.io/r/base/library.html", tmp, fixed = TRUE))) }) From dba718b6f22491c5aa92c3d30880793d376e21ad Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Mon, 8 Apr 2024 07:48:24 -0400 Subject: [PATCH 21/21] conditional autolink --- R/autolink.R | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/R/autolink.R b/R/autolink.R index 75ccbf39..4c743060 100644 --- a/R/autolink.R +++ b/R/autolink.R @@ -1,22 +1,28 @@ .autolink <- function(path = ".") { - # everything wrapped in tryCatch() because especially error prone with weird pandoc memory errors + html_files <- c( fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.html$", fail = FALSE), fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.html$", fail = FALSE)) - for (h in html_files) { - tmp <- try(downlit::downlit_html_path(h, h), silent = TRUE) - if (inherits(tmp, "try-error")) { - cli::cli_alert_danger(sprintf("Failed to auto-link: %s", h)) - } - } md_files <- c( fs::dir_ls(fs::path_join(c(path, "docs/vignettes")), regexp = "\\.md$", fail = FALSE), fs::dir_ls(fs::path_join(c(path, "docs/man")), regexp = "\\.md$", fail = FALSE)) - for (m in md_files) { - tmp <- try(downlit::downlit_md_path(m, m), silent = TRUE) - if (inherits(tmp, "try-error")) { - cli::cli_alert_danger(sprintf("Failed to auto-link: %s", h)) + + + if (isTRUE(.doc_type(path) %in% "quarto_website")) { + for (h in html_files) { + tmp <- try(downlit::downlit_html_path(h, h), silent = TRUE) + if (inherits(tmp, "try-error")) { + cli::cli_alert_danger(sprintf("Failed to auto-link: %s", h)) + } + } + + } else { + for (m in md_files) { + tmp <- try(downlit::downlit_md_path(m, m), silent = TRUE) + if (inherits(tmp, "try-error")) { + cli::cli_alert_danger(sprintf("Failed to auto-link: %s", h)) + } } } }