From 588af2b2c26416c57550496b37b39b8b13e4afed Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Sun, 5 Jan 2025 10:55:10 -0500 Subject: [PATCH] Do not render README.qmd automatically (#302) * Do not render README.qmd automatically * news: breaking change --- DESCRIPTION | 2 +- NEWS.md | 4 ++ R/import_readme.R | 42 ++++-------- tests/testthat/_snaps/docsify/render_docs.md | 71 ++++++++++---------- tests/testthat/_snaps/docute/render_docs.md | 71 ++++++++++---------- 5 files changed, 88 insertions(+), 102 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 01c9737..9858701 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.4.0 +Version: 0.4.0.9000 Authors@R: c(person(given = "Etienne", family = "Bacher", diff --git a/NEWS.md b/NEWS.md index efbc47e..561a6d1 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,10 @@ ## Development +Breaking changes: + +* Do not render README.qmd to markdown automatically. Users should render them manually to make sure that the README on CRAN and Github is in sync with the Altdoc home page. + ## 0.4.0 ### Breaking changes diff --git a/R/import_readme.R b/R/import_readme.R index fbbc548..5e5b6df 100644 --- a/R/import_readme.R +++ b/R/import_readme.R @@ -5,7 +5,7 @@ # setup_docs() already created README.md if there is none, so if we don't find # any, it means the user has deleted it and we error - if (length(readme_files) == 0) { + if (!"README.md" %in% readme_files) { cli::cli_abort("README.md is mandatory.") } @@ -44,30 +44,6 @@ } } - # Render README if Rmd or qmd - # Do nothing if we only have a .md file - switch( - readme_type, - - # rmd -> md - "rmd" = { - pre <- fs::path_join(c(src_dir, "altdoc/preamble_vignettes_rmd.yml")) - pre <- tryCatch(.readlines(pre), error = function(e) NULL) - .qmd2md(src_file, src_dir, preamble = pre) - }, - - # qmd -> md - "qmd" = { - pre <- fs::path_join(c(src_dir, "altdoc/preamble_vignettes_qmd.yml")) - pre <- tryCatch(.readlines(pre), warning = function(w) NULL, error = function(e) NULL) - # process in-place for use on Github - # TODO: preambles inserted in the README often break Quarto websites. It's - # not a big problem to omit the preamble, but it would be good to - # investigate this, because I am not sure what is going on -VAB - .qmd2md(src_file, src_dir) - } - ) - tar_file <- fs::path_join(c(tar_dir, "README.md")) src_file <- fs::path_join(c(src_dir, "README.md")) fs::file_copy(src_file, tar_file, overwrite = TRUE) @@ -75,10 +51,15 @@ # Add the index page which includes README.md if (tool == "quarto_website") { - writeLines( - enc2utf8("{{< include README.md >}}"), - fs::path_join(c(tar_dir, "index.md")) - ) + if ("README.qmd" %in% readme_files) { + fs::file_copy(fs::path_join(c(src_dir, "README.qmd")), fs::path_join(c(tar_dir, "index.qmd"))) + } else { + writeLines( + enc2utf8("{{< include README.md >}}"), + fs::path_join(c(tar_dir, "index.md")) + ) + fs::file_copy(fs::path_join(c(src_dir, "README.md")), tar_dir) + } } tmp <- fs::path_join(c(src_dir, "README.markdown_strict_files")) @@ -87,4 +68,7 @@ } .update_freeze(src_dir, basename(src_file), successes = 1, fails = NULL, type = "README") cli::cli_alert_success("{.file README} imported.") + if ("README.qmd" %in% readme_files) { + cli::cli_alert("Altdoc does not render README.qmd automatically to markdown. Please ensure that your README.md file is in sync.") + } } diff --git a/tests/testthat/_snaps/docsify/render_docs.md b/tests/testthat/_snaps/docsify/render_docs.md index 39d5900..817e3ea 100644 --- a/tests/testthat/_snaps/docsify/render_docs.md +++ b/tests/testthat/_snaps/docsify/render_docs.md @@ -4,42 +4,41 @@ .readlines("docs/README.md") Output [1] "" - [2] "" - [3] "" - [4] "" - [5] "# testpkg.altdoc" - [6] "" - [7] "" - [8] "" - [9] "[![R-universe status" - [10] "badge](https://grantmcdermott.r-universe.dev/badges/plot2)](https://grantmcdermott.r-universe.dev)" - [11] "" - [12] "" - [13] "The goal of testpkg.altdoc is to …" - [14] "" - [15] "## Installation" - [16] "" - [17] "You can install the development version of testpkg.altdoc like so:" - [18] "" - [19] "``` r" - [20] "# FILL THIS IN! HOW CAN PEOPLE INSTALL YOUR DEV PACKAGE?" - [21] "```" - [22] "" - [23] "## Example" - [24] "" - [25] "This is a basic example which shows you how to solve a common problem:" - [26] "" - [27] "``` r" - [28] "library(testpkg.altdoc)" - [29] "summary(cars)" - [30] "#> speed dist " - [31] "#> Min. : 4.0 Min. : 2.00 " - [32] "#> 1st Qu.:12.0 1st Qu.: 26.00 " - [33] "#> Median :15.0 Median : 36.00 " - [34] "#> Mean :15.4 Mean : 42.98 " - [35] "#> 3rd Qu.:19.0 3rd Qu.: 56.00 " - [36] "#> Max. :25.0 Max. :120.00" - [37] "```" + [2] "" + [3] "" + [4] "# testpkg.altdoc" + [5] "" + [6] "" + [7] "" + [8] "[![R-universe status" + [9] "badge](https://grantmcdermott.r-universe.dev/badges/plot2)](https://grantmcdermott.r-universe.dev)" + [10] "" + [11] "" + [12] "The goal of testpkg.altdoc is to …" + [13] "" + [14] "## Installation" + [15] "" + [16] "You can install the development version of testpkg.altdoc like so:" + [17] "" + [18] "``` r" + [19] "# FILL THIS IN! HOW CAN PEOPLE INSTALL YOUR DEV PACKAGE?" + [20] "```" + [21] "" + [22] "## Example" + [23] "" + [24] "This is a basic example which shows you how to solve a common problem:" + [25] "" + [26] "``` r" + [27] "library(testpkg.altdoc)" + [28] "summary(cars)" + [29] "#> speed dist " + [30] "#> Min. : 4.0 Min. : 2.00 " + [31] "#> 1st Qu.:12.0 1st Qu.: 26.00 " + [32] "#> Median :15.0 Median : 36.00 " + [33] "#> Mean :15.4 Mean : 42.98 " + [34] "#> 3rd Qu.:19.0 3rd Qu.: 56.00 " + [35] "#> Max. :25.0 Max. :120.00" + [36] "```" --- diff --git a/tests/testthat/_snaps/docute/render_docs.md b/tests/testthat/_snaps/docute/render_docs.md index 593e63a..1464fd5 100644 --- a/tests/testthat/_snaps/docute/render_docs.md +++ b/tests/testthat/_snaps/docute/render_docs.md @@ -4,42 +4,41 @@ .readlines("docs/README.md") Output [1] "" - [2] "" - [3] "" - [4] "" - [5] "# testpkg.altdoc" - [6] "" - [7] "" - [8] "" - [9] "[![R-universe status" - [10] "badge](https://grantmcdermott.r-universe.dev/badges/plot2)](https://grantmcdermott.r-universe.dev)" - [11] "" - [12] "" - [13] "The goal of testpkg.altdoc is to …" - [14] "" - [15] "## Installation" - [16] "" - [17] "You can install the development version of testpkg.altdoc like so:" - [18] "" - [19] "``` r" - [20] "# FILL THIS IN! HOW CAN PEOPLE INSTALL YOUR DEV PACKAGE?" - [21] "```" - [22] "" - [23] "## Example" - [24] "" - [25] "This is a basic example which shows you how to solve a common problem:" - [26] "" - [27] "``` r" - [28] "library(testpkg.altdoc)" - [29] "summary(cars)" - [30] "#> speed dist " - [31] "#> Min. : 4.0 Min. : 2.00 " - [32] "#> 1st Qu.:12.0 1st Qu.: 26.00 " - [33] "#> Median :15.0 Median : 36.00 " - [34] "#> Mean :15.4 Mean : 42.98 " - [35] "#> 3rd Qu.:19.0 3rd Qu.: 56.00 " - [36] "#> Max. :25.0 Max. :120.00" - [37] "```" + [2] "" + [3] "" + [4] "# testpkg.altdoc" + [5] "" + [6] "" + [7] "" + [8] "[![R-universe status" + [9] "badge](https://grantmcdermott.r-universe.dev/badges/plot2)](https://grantmcdermott.r-universe.dev)" + [10] "" + [11] "" + [12] "The goal of testpkg.altdoc is to …" + [13] "" + [14] "## Installation" + [15] "" + [16] "You can install the development version of testpkg.altdoc like so:" + [17] "" + [18] "``` r" + [19] "# FILL THIS IN! HOW CAN PEOPLE INSTALL YOUR DEV PACKAGE?" + [20] "```" + [21] "" + [22] "## Example" + [23] "" + [24] "This is a basic example which shows you how to solve a common problem:" + [25] "" + [26] "``` r" + [27] "library(testpkg.altdoc)" + [28] "summary(cars)" + [29] "#> speed dist " + [30] "#> Min. : 4.0 Min. : 2.00 " + [31] "#> 1st Qu.:12.0 1st Qu.: 26.00 " + [32] "#> Median :15.0 Median : 36.00 " + [33] "#> Mean :15.4 Mean : 42.98 " + [34] "#> 3rd Qu.:19.0 3rd Qu.: 56.00 " + [35] "#> Max. :25.0 Max. :120.00" + [36] "```" ---