diff --git a/NEWS.md b/NEWS.md index 25ad250..2d31ff0 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,7 +4,10 @@ ### Breaking changes -* Simplified rendering for Quarto websites. Previously, the website was rendered into `_quarto/_site` and manually copied over to `docs/`. The new version removes this logic and instead uses the `output-dir` project option. To transition, change `quarto_website.yml` to: +* Simplified rendering for Quarto websites. Previously, the website was rendered + into `_quarto/_site` and manually copied over to `docs/`. The new version removes + this logic and instead uses the `output-dir` project option. To transition, change + `quarto_website.yml` to: ``` yml project: output-dir: ../docs/ @@ -12,12 +15,21 @@ ### New features -* `render_docs(freeze = TRUE)` now works correctly when output is `"quarto_website"`. Freezing a document needs to be set either at a project or per-file level. To do so, add to either `quarto_website.yml` or the frontmatter of a file: +* `render_docs(freeze = TRUE)` now works correctly when output is `"quarto_website"`. + Freezing a document needs to be set either at a project or per-file level. To do + so, add to either `quarto_website.yml` or the frontmatter of a file: + ``` yml execute: freeze: auto ``` -* For Quarto websites, `render_docs()` can use the `downlit` package to automatically link function calls to their documentation on the web. Turn off by modifying the `code-link` line in `altdoc/quarto_website.yml` +* For Quarto websites, `render_docs()` can use the `downlit` package to automatically + link function calls to their documentation on the web. Turn off by modifying + the `code-link` line in `altdoc/quarto_website.yml` +* Citation is now formatted with HTML instead of verbatim (#282, Achim Zeileis). +* The `\doi{}` tags in Rd files are now linked once rendered (#282, Achim Zeileis). + + ### Other changes diff --git a/R/import_misc.R b/R/import_misc.R index 9cfd508..99bd898 100644 --- a/R/import_misc.R +++ b/R/import_misc.R @@ -13,8 +13,19 @@ tryCatch( { name <- .pkg_name(src_dir) - cite <- utils::capture.output(print(utils::citation(name))) - c("# Citation", "", "```verbatim", cite, "```") + cite <- utils::citation(name) + head <- vapply(cite, function(x) { + if (is.null(x$header)) { + "" + } else { + paste0(x$header, "\n\n") + } + }, character(1)) + if (!is.null(attr(cite, "mheader"))) { + head[1] <- paste0(attr(cite, "mheader"), "\n\n", head[1]) + } + cite <- paste0(head, format(cite, style = "html")) + c("# Citation", "", paste(cite, collapse = "\n\n")) }, error = function(e) NULL) ) diff --git a/R/rd2qmd.R b/R/rd2qmd.R index 08ee9b8..2acd959 100644 --- a/R/rd2qmd.R +++ b/R/rd2qmd.R @@ -25,9 +25,12 @@ # doesn't escape symbols between two $. tmp <- gsub("\\$", "\\\\$", tmp) + # process \doi{...} tags that were expanded to \Sexpr[results=rd]{tools:::Rd_expr_doi("...")} + tmp <- gsub("(\\\\Sexpr\\[results=rd\\]\\{tools:::Rd_expr_doi\\(\\\")([^\\\"]+)(\\\"\\)\\})", "[doi:\\2](https://doi.org/\\2)", tmp) + # examples: evaluate code blocks (assume examples are always last) pkg <- .pkg_name(path) - pkg_load <- paste0("library(", pkg, ")") + pkg_load <- paste0("library(\"", pkg, "\")") idx <- which(tmp == "
print
, hello_r6
"
+ [48] ""
+ [49] "## Examples"
+ [50] ""
+ [51] "``` r"
+ [52] "library(\"testpkg.altdoc\")"
+ [53] ""
+ [54] "hello_base()"
+ [55] "```"
+ [56] ""
+ [57] " [1] \"Hello, world!\""
+ [58] ""
+ [59] "``` r"
+ [60] "mtcars$drat <- mtcars$drat + 1"
+ [61] "head(mtcars[[\"drat\"]], 2)"
+ [62] "```"
+ [63] ""
+ [64] " [1] 4.9 4.9"
---
@@ -374,7 +385,7 @@
[31] "## Examples"
[32] ""
[33] "``` r"
- [34] "library(testpkg.altdoc)"
+ [34] "library(\"testpkg.altdoc\")"
[35] ""
[36] ""
[37] "examplesIf_true()"
@@ -420,7 +431,7 @@
[31] "## Examples"
[32] ""
[33] "``` r"
- [34] "library(testpkg.altdoc)"
+ [34] "library(\"testpkg.altdoc\")"
[35] ""
[36] ""
[37] "examplesIf_false()"
diff --git a/tests/testthat/_snaps/docute/render_docs.md b/tests/testthat/_snaps/docute/render_docs.md
index bb45a2f..593e63a 100644
--- a/tests/testthat/_snaps/docute/render_docs.md
+++ b/tests/testthat/_snaps/docute/render_docs.md
@@ -156,22 +156,33 @@
[35] ""
[36] "Some value"
[37] ""
- [38] "## Examples"
+ [38] "## References"
[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"
+ [40] "Ihaka R, Gentleman R (1996). R: A Language for Data Analysis and"
+ [41] "Graphics. Journal of Computational and Graphical Statistics."
+ [42] "5(3), 299–314."
+ [43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
+ [44] ""
+ [45] "## See Also"
+ [46] ""
+ [47] "print
, hello_r6
"
+ [48] ""
+ [49] "## Examples"
+ [50] ""
+ [51] "``` r"
+ [52] "library(\"testpkg.altdoc\")"
+ [53] ""
+ [54] "hello_base()"
+ [55] "```"
+ [56] ""
+ [57] " [1] \"Hello, world!\""
+ [58] ""
+ [59] "``` r"
+ [60] "mtcars$drat <- mtcars$drat + 1"
+ [61] "head(mtcars[[\"drat\"]], 2)"
+ [62] "```"
+ [63] ""
+ [64] " [1] 4.9 4.9"
---
@@ -365,7 +376,7 @@
[31] "## Examples"
[32] ""
[33] "``` r"
- [34] "library(testpkg.altdoc)"
+ [34] "library(\"testpkg.altdoc\")"
[35] ""
[36] ""
[37] "examplesIf_true()"
@@ -411,7 +422,7 @@
[31] "## Examples"
[32] ""
[33] "``` r"
- [34] "library(testpkg.altdoc)"
+ [34] "library(\"testpkg.altdoc\")"
[35] ""
[36] ""
[37] "examplesIf_false()"
diff --git a/tests/testthat/_snaps/mkdocs/render_docs.md b/tests/testthat/_snaps/mkdocs/render_docs.md
index 21643de..09a527c 100644
--- a/tests/testthat/_snaps/mkdocs/render_docs.md
+++ b/tests/testthat/_snaps/mkdocs/render_docs.md
@@ -55,22 +55,33 @@
[35] ""
[36] "Some value"
[37] ""
- [38] "## Examples"
+ [38] "## References"
[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"
+ [40] "Ihaka R, Gentleman R (1996). R: A Language for Data Analysis and"
+ [41] "Graphics. Journal of Computational and Graphical Statistics."
+ [42] "5(3), 299–314."
+ [43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
+ [44] ""
+ [45] "## See Also"
+ [46] ""
+ [47] "print
, hello_r6
"
+ [48] ""
+ [49] "## Examples"
+ [50] ""
+ [51] "``` r"
+ [52] "library(\"testpkg.altdoc\")"
+ [53] ""
+ [54] "hello_base()"
+ [55] "```"
+ [56] ""
+ [57] " [1] \"Hello, world!\""
+ [58] ""
+ [59] "``` r"
+ [60] "mtcars$drat <- mtcars$drat + 1"
+ [61] "head(mtcars[[\"drat\"]], 2)"
+ [62] "```"
+ [63] ""
+ [64] " [1] 4.9 4.9"
---
diff --git a/tests/testthat/examples/testpkg.altdoc/R/hello_base.R b/tests/testthat/examples/testpkg.altdoc/R/hello_base.R
index b2da6af..55432bf 100644
--- a/tests/testthat/examples/testpkg.altdoc/R/hello_base.R
+++ b/tests/testthat/examples/testpkg.altdoc/R/hello_base.R
@@ -2,11 +2,27 @@
#'
#' @param x A parameter
#'
+#' @details
+#' Some code with weird symbols: `pl$when(condition)` and `pl$then(output)`
+#'
+#' Some equations: \eqn{\partial Y / \partial X = a + \varepsilon/2}
+#'
+#'
#' @return Some value
#' @export
#'
+#' @seealso \code{\link[base]{print}}, \code{\link{hello_r6}}
+#'
+#' @references Ihaka R, Gentleman R (1996).
+#' R: A Language for Data Analysis and Graphics.
+#' \emph{Journal of Computational and Graphical Statistics}. \bold{5}(3), 299--314.
+#' \doi{10.2307/139080}
+#'
#' @examples
#' hello_base()
+#'
+#' mtcars$drat <- mtcars$drat + 1
+#' head(mtcars[["drat"]], 2)
hello_base <- function(x = 2) {
print("Hello, world!")
}
diff --git a/tests/testthat/examples/testpkg.altdoc/man/hello_base.Rd b/tests/testthat/examples/testpkg.altdoc/man/hello_base.Rd
index 9cb7d26..e7a7f83 100644
--- a/tests/testthat/examples/testpkg.altdoc/man/hello_base.Rd
+++ b/tests/testthat/examples/testpkg.altdoc/man/hello_base.Rd
@@ -26,3 +26,12 @@ hello_base()
mtcars$drat <- mtcars$drat + 1
head(mtcars[["drat"]], 2)
}
+\references{
+Ihaka R, Gentleman R (1996).
+R: A Language for Data Analysis and Graphics.
+\emph{Journal of Computational and Graphical Statistics}. \bold{5}(3), 299--314.
+\doi{10.2307/139080}
+}
+\seealso{
+\code{\link[base]{print}}, \code{\link{hello_r6}}
+}