From c5cc6b7fc14376d4808dbd21f7c3fab60a5e0abf Mon Sep 17 00:00:00 2001 From: Edoardo Mancini Date: Thu, 12 Sep 2024 12:20:06 +0000 Subject: [PATCH] #184 Updated documentation --- .github/pull_request_template.md | 1 + .github/workflows/update_post_dates.yml | 2 +- R/create_blogpost.R | 2 +- R/help_create_blogpost.R | 2 +- R/readme.md | 1 + R/update_post_dates.R | 4 +- README.md | 7 ++- inst/template/template.txt | 5 +- posts/new_post_my_blog/appendix.R | 73 ------------------------- posts/new_post_my_blog/my_blog.qmd | 42 -------------- 10 files changed, 14 insertions(+), 125 deletions(-) delete mode 100644 posts/new_post_my_blog/appendix.R delete mode 100644 posts/new_post_my_blog/my_blog.qmd diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 991098dd..e3b06498 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -3,6 +3,7 @@ Thank you for your Pull Request! We have developed this task checklist to help w Please check off each taskbox as an acknowledgment that you completed the task or check off that it is not relevant to your Pull Request. This checklist is part of the Github Action workflows and the Pull Request will not be merged into the `main` branch until you have checked off each task. - [ ] Place Closes # into the beginning of your Pull Request Title (Use Edit button in top-right if you need to update), and make sure the corresponding issue is linked in the Development section on the right hand side +- [ ] Ensure your new post folder is of the form `"posts/zzz_DO_NOT_EDIT_"`. This is so that the post date can be auto-updated upon the merge into `main`. - [ ] Run the script from `CICD.R` line by line to first check the spelling in your post and then to make sure your code is compatible with our code-style. Address any incongruences by following the instructions in the file! - [ ] Choose (possibly several) `tag(s)` or categories from the current list: ` c("Metadata", "SDTM", "ADaM", "TLG", "Shiny", "Community", "Conferences", "Submissions", "Technical")` for your blog post. If you cannot find anything that fits your blog post, propose a new tag to the maintainers! Note: if you use a tag not from this list, the "Check Post Tags" CICD pipeline will error. We occasionally tidy up all `tags` for consistency. - [ ] Add a short description for your blog post in the `description` field at the top of the markdown document. diff --git a/.github/workflows/update_post_dates.yml b/.github/workflows/update_post_dates.yml index c3c0acb7..d725cb41 100644 --- a/.github/workflows/update_post_dates.yml +++ b/.github/workflows/update_post_dates.yml @@ -3,7 +3,7 @@ name: Update post dates on: push: branches: - - 'cicd_testing' + - 'main' jobs: Update-post-dates: diff --git a/R/create_blogpost.R b/R/create_blogpost.R index 786e1a44..8af17e24 100644 --- a/R/create_blogpost.R +++ b/R/create_blogpost.R @@ -12,7 +12,7 @@ print(allowed_tags) # Fill in the info, e.g.: create_post( post_name = "My Blog", # needs to be character vector (length 1) - post_date = "2024-12-01", # needs to be character vector (length 1) + post_date = "2024-12-01", # needs to be length 1character vector and will be auto-updated when your post is merged description = "", # you can fill the description in later as well author = c("My Name"), # one or more authors are permitted cover_image = "pharmaverse", # chose one of the above (see line 8) diff --git a/R/help_create_blogpost.R b/R/help_create_blogpost.R index 769e5ff2..4ec112d2 100644 --- a/R/help_create_blogpost.R +++ b/R/help_create_blogpost.R @@ -45,7 +45,7 @@ create_post <- function(post_name, # Prepare values snake_name <- gsub(" ", "_", tolower(gsub("(.)([A-Z])", "\\1 \\2", post_name))) - short_name <- paste(post_date, snake_name, sep = "_") + short_name <- paste("zzz_DO_NOT_EDIT", snake_name, sep = "_") if (short_name != short_name %>% stringr::str_trunc(30)) { message("For the folder creation:") diff --git a/R/readme.md b/R/readme.md index a73bc978..63ca8439 100644 --- a/R/readme.md +++ b/R/readme.md @@ -10,3 +10,4 @@ Some of these files help in creating/developing blog-posts, others are used by o - `help_create_blogpost.R`: script containing the function(s) used by `create_blogpost.R` - `switch.R`: Used by CICD spellcheck workflow. - `check_post_tags.R`: Used by Check-Post-Tags CICD workflow +- `update_post_dates.R`: Used by Update-Post_Dates CICD workflow diff --git a/R/update_post_dates.R b/R/update_post_dates.R index 9d3cf983..2568bc3f 100644 --- a/R/update_post_dates.R +++ b/R/update_post_dates.R @@ -1,5 +1,5 @@ # Get list of post folders where date has to be edited ---- -post_folders <- list.files("posts", recursive = FALSE, pattern = "new_post") +post_folders <- list.files("posts", recursive = FALSE, pattern = "zzz_DO_NOT_EDIT") # Prepare date to replace in a blog post and folder ---- formatted_date <- format(Sys.Date(), "%Y-%m-%d") @@ -47,7 +47,7 @@ for (folder in post_folders){ writeLines(new_lines, blog_post_path) # Update date in folder ---- - new_folder_name <- stringr::str_replace(folder, "new_post", formatted_date) + new_folder_name <- stringr::str_replace(folder, "zzz_DO_NOT_EDIT", formatted_date) file.rename(file.path("posts", folder),file.path("posts", new_folder_name)) cli::cli_inform(paste("Folder renamed for post:", yaml_list$title)) diff --git a/README.md b/README.md index 7debc10c..e7739111 100644 --- a/README.md +++ b/README.md @@ -64,11 +64,12 @@ After that you can go wild, but we do ask that it is kept short! - Source the script `help_create_blogpost.R` from within the `create_blogpost.R` file. -- Enter your information into the `create_post` function. - Please note that we do not currently allow users to specify their own categories (or `tags`), so you must choose (possibly several) from this list: `c("Metadata", "SDTM", "ADaM", "TLG", "Shiny", "Community", "Conferences", "Submissions", "Technical")`. +- Enter your information into the `create_post` function. For the post date, feel free to put a placeholder date as it will be automatically replaced once the post is merged onto `main`. + Please note that we do not currently allow users to specify their own categories (or `tags`), so you must choose (possibly several) from this list: `c("Metadata", "SDTM", "ADaM", "TLG", "Shiny", "Community", "Conferences", "Submissions", "Technical")`. - Running that function will create a subfolder with a quarto file (`*.qmd`) in the `posts/` folder. - Both should be named based on the supplied `post_date` and `post_name` information. + The folder will be named `zzz_DO_NOT_EDIT_`, and the `zzz_DO_NOT_EDIT` portion of the folder name + will also be automatically replaced once the post is merged onto `main`. - Open the newly created folder and start working within the `*.qmd` file. diff --git a/inst/template/template.txt b/inst/template/template.txt index 217a9cc1..2f830b68 100644 --- a/inst/template/template.txt +++ b/inst/template/template.txt @@ -3,11 +3,12 @@ title: [TITLE] author: [AUTHOR] description: [DESCR] +# Note that the date below will be auto-updated when the post is merged. date: [DATE] -# please do not use any non-default categories. +# Please do not use any non-default categories. # You can find the default categories in the repository README.md categories: [[TAG]] -# feel free to change the image +# Feel free to change the image image: [IMG] --- diff --git a/posts/new_post_my_blog/appendix.R b/posts/new_post_my_blog/appendix.R deleted file mode 100644 index c69926b0..00000000 --- a/posts/new_post_my_blog/appendix.R +++ /dev/null @@ -1,73 +0,0 @@ -suppressMessages(library(dplyr)) -# markdown helpers -------------------------------------------------------- - -markdown_appendix <- function(name, content) { - paste(paste("##", name, "{.appendix}"), " ", content, sep = "\n") -} -markdown_link <- function(text, path) { - paste0("[", text, "](", path, ")") -} - - - -# worker functions -------------------------------------------------------- - -insert_source <- function(repo_spec, name, - collection = "posts", - branch = "main", - host = "https://github.com", - text = "Source", - file_name) { - path <- paste( - host, - repo_spec, - "tree", - branch, - collection, - name, - file_name, - sep = "/" - ) - return(markdown_link(text, path)) -} - -insert_timestamp <- function(tzone = Sys.timezone()) { - time <- lubridate::now(tzone = tzone) - stamp <- as.character(time, tz = tzone, usetz = TRUE) - return(stamp) -} - -insert_lockfile <- function(repo_spec, name, - collection = "posts", - branch = "main", - host = "https://github.com", - text = "Session info") { - path <- path <- "https://pharmaverse.github.io/blog/session_info.html" - - return(markdown_link(text, path)) -} - - - -# top level function ------------------------------------------------------ - -insert_appendix <- function(repo_spec, name, collection = "posts", file_name) { - appendices <- paste( - markdown_appendix( - name = "Last updated", - content = insert_timestamp() - ), - " ", - markdown_appendix( - name = "Details", - content = paste( - insert_source(repo_spec, name, collection, file_name = file_name), - # get renv information, - insert_lockfile(repo_spec, name, collection), - sep = ", " - ) - ), - sep = "\n" - ) - knitr::asis_output(appendices) -} diff --git a/posts/new_post_my_blog/my_blog.qmd b/posts/new_post_my_blog/my_blog.qmd deleted file mode 100644 index 57af5644..00000000 --- a/posts/new_post_my_blog/my_blog.qmd +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: My Blog -author: -- name: My Name -description: '' -date: 'zzz' -categories: -- Metadata -- SDTM -- ADaM -- TLG -- Shiny -- Community -- Conferences -- Submissions -- Technical -image: pharmaverse.png ---- - - - -```{r setup, include=FALSE} -long_slug <- "fill_in_date_my__blog" -# renv::use(lockfile = "renv.lock") -``` - - - - - - - - -```{r, echo=FALSE} -source("appendix.R") -insert_appendix( - repo_spec = "pharmaverse/blog", - name = long_slug, - # file_name should be the name of your file - file_name = list.files() %>% stringr::str_subset(".qmd") %>% first() -) -```