merged branches

.Rbuildignore

@@ -21,3 +21,5 @@ man-roxygen
 ^flir$
 
 ^air.toml$
+^\.positai$
+^\.claude$

.gitignore

@@ -5,3 +5,4 @@
 docs
 inst/doc
 altdoc/freeze.rds
+.positai

DESCRIPTION

@@ -46,6 +46,6 @@ Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
 Language: en-US
 VignetteBuilder: knitr
+Config/roxygen2/version: 8.0.0

NEWS.md

@@ -8,6 +8,12 @@
 
 ### Bug fixes
 
+* Vignettes in subfolders (e.g., `vignettes/articles/`) are now discovered 
+  recursively when using `quarto_website`. (#355)
+
+* Custom sidebars with singleton entries in `quarto_website.yml` are now 
+  properly processed. (#355)
+
 * In 0.5.0, we announced that `README.qmd` wouldn't be automatically rendered,
   but this still happened when `output = "quarto_website"`. This is now fixed,
   meaning that `altdoc` uses `README.md` over `README.qmd` (#354).

R/import_man.R

@@ -95,7 +95,6 @@
 
     successes <- which(conversion_worked == "success")
     fails <- which(conversion_worked == "failure")
-    skipped_internal <- which(conversion_worked == "skipped_internal")
     skipped_unchanged <- which(conversion_worked == "skipped_unchanged")
 
     .update_freeze(src_dir, man_source, successes, fails, type = "man")
@@ -105,12 +104,6 @@
     # indent bullet points
     cli::cli_div(theme = list(ul = list(`margin-left` = 2, before = "")))
 
-    if (length(skipped_internal) > 0) {
-        cli::cli_alert(
-            "{length(skipped_internal)} .Rd files skipped because they document internal functions."
-        )
-    }
-
     if (length(skipped_unchanged) > 0) {
         cli::cli_alert(
             "{length(skipped_unchanged)} .Rd files skipped because they didn't change."
@@ -151,15 +144,6 @@
     destination_qmd <- fs::path_join(c(destination_dir, paste0(fn, ".qmd")))
     destination_md <- fs::path_join(c(destination_dir, paste0(fn, ".md")))
 
-    # Skip internal functions
-    flag <- tryCatch(
-        any(grepl("\\keyword\\{internal\\}", .readlines(origin_Rd))),
-        error = function(e) FALSE
-    )
-    if (isTRUE(flag)) {
-        return("skipped_internal")
-    }
-
     # Skip file when frozen
     if (isTRUE(freeze)) {
         flag <- .is_frozen(

R/settings.R

@@ -28,6 +28,20 @@
         }
 
         fs::dir_copy(src, tar_dir, overwrite = TRUE)
+
+        # For non-quarto tools, also copy pkgdown.yml to the root of docs/ so
+        # that downlit can find it at <url>/pkgdown.yml. For the quarto_website
+        # tool this is handled in .finalize_quarto_website().
+        if (!grepl("^quarto", tool)) {
+            pkgdown_src <- fs::path_join(c(path, "altdoc", "pkgdown.yml"))
+            if (fs::file_exists(pkgdown_src)) {
+                fs::file_copy(
+                    pkgdown_src,
+                    fs::path_join(c(tar_dir, "pkgdown.yml")),
+                    overwrite = TRUE
+                )
+            }
+        }
     }
 
     fn <- switch(

R/settings_quarto_website.R

@@ -51,13 +51,23 @@
 
     # this can be done automatically with `project:` > `resources: ../altdoc/`
     fs::dir_copy(fs::path_join(c(path, "altdoc")), tar, overwrite = TRUE)
+
+    # Also copy pkgdown.yml to the root of docs/ so that downlit can find it at
+    # <url>/pkgdown.yml when auto-linking function calls in vignettes and articles.
+    # fs::dir_copy() copies altdoc/ as a subdirectory of docs/ (creating
+    # docs/altdoc/pkgdown.yml), but downlit looks for it at the website root.
+    pkgdown_src <- fs::path_join(c(path, "altdoc", "pkgdown.yml"))
+    if (fs::file_exists(pkgdown_src)) {
+        fs::file_copy(pkgdown_src, fs::path_join(c(tar, "pkgdown.yml")), overwrite = TRUE)
+    }
 }
 
 .sidebar_vignettes_quarto_website <- function(sidebar, path) {
     fn_vignettes <- list.files(
         fs::path_join(c(path, "_quarto/vignettes")),
         pattern = "\\.qmd$|\\.Rmd|\\.pdf$",
-        full.names = TRUE
+        full.names = TRUE,
+        recursive = TRUE
     )
     fn_man <- list.files(
         fs::path_join(c(path, "_quarto/man")),
@@ -70,7 +80,7 @@
     fn_vignettes <- gsub(".*_quarto.", "", fn_vignettes)
 
     yml <- paste(sidebar, collapse = "\n")
-    yml <- yaml::yaml.load(yml)
+    yml <- yaml::yaml.load(yml, handlers = list(seq = function(x) as.list(x)))
 
     # reverse order because we delete elements
     for (i in rev(seq_along(yml$website$sidebar$contents))) {

man-roxygen/altdoc_autolink.R

@@ -2,7 +2,7 @@
 #'
 #' When the `code-link` format setting is `true` in `altdoc/quarto_website.yml` and the `downlit` package is installed, `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`.
+#' 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`. The `pkgdown.yml` file is automatically copied to the root of the `docs/` directory so that `downlit` can find it at `<url>/pkgdown.yml`.
 #'
-#' Importantly, `downlit` requires the `pkgdown.yml` file 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.
+#' Importantly, `downlit` requires the `pkgdown.yml` file 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, since the file needs to be deployed before `downlit` can fetch it. Subsequent renders after the first deployment will have correct links.
 #'

tests/testthat/test-import_man.R

@@ -27,7 +27,7 @@ test_that("rendering fails", {
     )
 })
 
-test_that("rendering skipped because internal", {
+test_that("rendering internal functions", {
     skip_if(!.quarto_is_installed())
     source <- test_path("examples/examples-man/is-internal.Rd")
     dest <- tempfile(fileext = ".Rd")
@@ -38,6 +38,7 @@ test_that("rendering skipped because internal", {
     fs::dir_create("man")
     fs::file_copy(dest, "man")
     src <- fs::path_ext_remove(list.files("man"))
+    # Internal functions should now be converted successfully
     expect_identical(
         .render_one_man(
             src,
@@ -47,7 +48,7 @@ test_that("rendering skipped because internal", {
             freeze = FALSE,
             hashes = NULL
         ),
-        "skipped_internal"
+        "success"
     )
 })
 

tests/testthat/test-render_docs.R

@@ -260,6 +260,35 @@
     )
 })
 
+test_that("quarto: pkgdown.yml is at docs root after render_docs", {
+    skip_on_cran()
+    skip_if(.is_windows() && .on_ci(), "Windows on CI")
+    skip_if(!.quarto_is_installed())
+
+    ### 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")
+    desc::desc_add_urls("https://mywebsite.com")
+
+    ### generate docs
+    install.packages(".", repos = NULL, type = "source")
+    setup_docs("quarto_website")
+    expect_no_error(render_docs(verbose = .on_ci()))
+
+    ### pkgdown.yml must be at the root of docs/ so that downlit can find it at
+    ### <url>/pkgdown.yml when auto-linking function calls in vignettes
+    expect_true(fs::file_exists("docs/pkgdown.yml"))
+    docs_pkgdown <- yaml::read_yaml("docs/pkgdown.yml")
+    expect_equal(docs_pkgdown$urls$reference, "https://mywebsite.com/man")
+})
+
 test_that("files in man/figures are copied to docs/help/figures", {
     skip_on_cran()
     skip_if(!.quarto_is_installed())
@@ -386,7 +415,7 @@
     expect_snapshot(
         cat(.readlines("altdoc/pkgdown.yml"), sep = "\n"),
         transform = function(x) {
             first_timestamp <<- regmatches(x, gregexpr(timestamp_regex, x)) |>
                 unlist()
             x <- gsub("\\d+\\.\\d+\\.\\d+(\\.\\d+|)", "0.0.0", x)
             x <- gsub(
@@ -413,6 +442,12 @@
 
     expect_true(first_timestamp != second_timestamp)
 
+    ### pkgdown.yml must be at the root of docs/ so that downlit can find it at
+    ### <url>/pkgdown.yml when auto-linking function calls in vignettes
+    expect_true(fs::file_exists("docs/pkgdown.yml"))
+    docs_pkgdown <- yaml::read_yaml("docs/pkgdown.yml")
+    expect_equal(docs_pkgdown$urls$reference, "https://mywebsite.com/man")
+
     ### render_docs() doesn't remove pre-existing fields in pkgdown.yml
     cat(
         "altdoc: 0.0.0