Skip to content

Commit

Permalink
citation & doi formatting (#282)
Browse files Browse the repository at this point in the history 
* process doi tags from Rd pages

* avoid non-standard evaluation in library()

* citation() formatting as HTML instead of verbatim

* add @references with doi and @Seealso for testing purposes

* add missing info in test pkg

* update snapshots

* formatting

* news

---------

Co-authored-by: Etienne Bacher <[email protected]>
Co-authored-by: Vincent Arel-Bundock <[email protected]>
  • Loading branch information
@zeileis @etiennebacher @vincentarelbundock
3 people authored Jul 5, 2024
1 parent ebf6545 commit 6116ed5
Show file tree
Hide file tree
Showing 8 changed files with 139 additions and 55 deletions.
18 changes: 15 additions & 3 deletions NEWS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,32 @@

### 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/
```
### 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

Expand Down
15 changes: 13 additions & 2 deletions R/import_misc.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
)
Expand Down
5 changes: 4 additions & 1 deletion R/rd2qmd.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 == "<h3>Examples</h3>")

if (length(idx) == 1) {
Expand Down
45 changes: 28 additions & 17 deletions tests/testthat/_snaps/docsify/render_docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -165,22 +165,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. <em>Journal of Computational and Graphical Statistics</em>."
[42] "<b>5</b>(3), 299–314."
[43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
[44] ""
[45] "## See Also"
[46] ""
[47] "<code>print</code>, <code>hello_r6</code>"
[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"

---

Expand Down Expand Up @@ -374,7 +385,7 @@
[31] "## Examples"
[32] ""
[33] "``` r"
[34] "library(testpkg.altdoc)"
[34] "library(\"testpkg.altdoc\")"
[35] ""
[36] ""
[37] "examplesIf_true()"
Expand Down Expand Up @@ -420,7 +431,7 @@
[31] "## Examples"
[32] ""
[33] "``` r"
[34] "library(testpkg.altdoc)"
[34] "library(\"testpkg.altdoc\")"
[35] ""
[36] ""
[37] "examplesIf_false()"
Expand Down
45 changes: 28 additions & 17 deletions tests/testthat/_snaps/docute/render_docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. <em>Journal of Computational and Graphical Statistics</em>."
[42] "<b>5</b>(3), 299–314."
[43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
[44] ""
[45] "## See Also"
[46] ""
[47] "<code>print</code>, <code>hello_r6</code>"
[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"

---

Expand Down Expand Up @@ -365,7 +376,7 @@
[31] "## Examples"
[32] ""
[33] "``` r"
[34] "library(testpkg.altdoc)"
[34] "library(\"testpkg.altdoc\")"
[35] ""
[36] ""
[37] "examplesIf_true()"
Expand Down Expand Up @@ -411,7 +422,7 @@
[31] "## Examples"
[32] ""
[33] "``` r"
[34] "library(testpkg.altdoc)"
[34] "library(\"testpkg.altdoc\")"
[35] ""
[36] ""
[37] "examplesIf_false()"
Expand Down
41 changes: 26 additions & 15 deletions tests/testthat/_snaps/mkdocs/render_docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. <em>Journal of Computational and Graphical Statistics</em>."
[42] "<b>5</b>(3), 299–314."
[43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
[44] ""
[45] "## See Also"
[46] ""
[47] "<code>print</code>, <code>hello_r6</code>"
[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"

---

Expand Down
16 changes: 16 additions & 0 deletions tests/testthat/examples/testpkg.altdoc/R/hello_base.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!")
}
9 changes: 9 additions & 0 deletions tests/testthat/examples/testpkg.altdoc/man/hello_base.Rd
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit 6116ed5

Please sign in to comment.