Skip to content

Commit

Permalink
Do not render README.qmd automatically (#302)
Browse files Browse the repository at this point in the history 
* Do not render README.qmd automatically

* news: breaking change
  • Loading branch information
@vincentarelbundock
vincentarelbundock authored Jan 5, 2025
1 parent c50ebef commit 588af2b
Show file tree
Hide file tree
Showing 5 changed files with 88 additions and 102 deletions.
2 changes: 1 addition & 1 deletion DESCRIPTION
View file
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
4 changes: 4 additions & 0 deletions NEWS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
42 changes: 13 additions & 29 deletions R/import_readme.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.")
}

Expand Down Expand Up @@ -44,41 +44,22 @@
}
}

# 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)
.check_md_structure(tar_file)

# 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"))
Expand All @@ -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.")
}
}
71 changes: 35 additions & 36 deletions tests/testthat/_snaps/docsify/render_docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,42 +4,41 @@
.readlines("docs/README.md")
Output
[1] ""
[2] ""
[3] "<!-- README.md is generated from README.Rmd. Please edit that file -->"
[4] ""
[5] "# testpkg.altdoc"
[6] ""
[7] "<!-- badges: start -->"
[8] ""
[9] "[![R-universe status"
[10] "badge](https://grantmcdermott.r-universe.dev/badges/plot2)](https://grantmcdermott.r-universe.dev)"
[11] "<!-- badges: end -->"
[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] "<!-- README.md is generated from README.Rmd. Please edit that file -->"
[3] ""
[4] "# testpkg.altdoc"
[5] ""
[6] "<!-- badges: start -->"
[7] ""
[8] "[![R-universe status"
[9] "badge](https://grantmcdermott.r-universe.dev/badges/plot2)](https://grantmcdermott.r-universe.dev)"
[10] "<!-- badges: end -->"
[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] "```"

---

Expand Down
71 changes: 35 additions & 36 deletions tests/testthat/_snaps/docute/render_docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,42 +4,41 @@
.readlines("docs/README.md")
Output
[1] ""
[2] ""
[3] "<!-- README.md is generated from README.Rmd. Please edit that file -->"
[4] ""
[5] "# testpkg.altdoc"
[6] ""
[7] "<!-- badges: start -->"
[8] ""
[9] "[![R-universe status"
[10] "badge](https://grantmcdermott.r-universe.dev/badges/plot2)](https://grantmcdermott.r-universe.dev)"
[11] "<!-- badges: end -->"
[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] "<!-- README.md is generated from README.Rmd. Please edit that file -->"
[3] ""
[4] "# testpkg.altdoc"
[5] ""
[6] "<!-- badges: start -->"
[7] ""
[8] "[![R-universe status"
[9] "badge](https://grantmcdermott.r-universe.dev/badges/plot2)](https://grantmcdermott.r-universe.dev)"
[10] "<!-- badges: end -->"
[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] "```"

---

Expand Down

0 comments on commit 588af2b

Please sign in to comment.