Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Do not render README.qmd automatically #302

Merged
merged 3 commits into from
Jan 5, 2025
Merged

Do not render README.qmd automatically #302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3b0aa6f
Do not render README.qmd automatically
vincentarelbundock Jan 4, 2025
753726f
Merge branch 'main' into issue296_readme
vincentarelbundock Jan 5, 2025
8ead690
news: breaking change
vincentarelbundock Jan 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion DESCRIPTION
View file
Open in desktop
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
Open in desktop
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.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you put this in a "Breaking changes" category?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

8ead690


## 0.4.0

### Breaking changes
Expand Down
42 changes: 13 additions & 29 deletions R/import_readme.R
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading