ropensci-org / roblog Goto Github PK

Recommend the use of the docs.ropensci.org URL (and to ensure the GitHub URL is in DESCRIPTION thus accessible from the pkgdown website).

cc @jeroen

• The idea would be to use hrbrthemes at first since it's fine, and to use theme_set in the first chunk of the blog post template.
• The theme would define a good text size for all parts of a plot.
• I hope it's possible to add default color scales this way the default scales would be viridis and colorblindr palettes for continuous and discrete variables by default.

@steffilazerte wrote

For consistency could we use the usethis::ui_done/usethis::ui_todo on the ro_check_urls too?

More messages, maybe TODOs à la usethis or blogdown.

Warn users about problems in their R code:

• Use library() not require()
• ...?

I do deploy locally these days, maybe some authors will do that (but they don't have to, if they don't want to install Hugo locally).

install.packages("roblog", repos = "https://dev.ropensci.org") results in

Warning in install.packages :
  package ‘roblog’ is not available (for R version 3.6.3 RC)

based on git2r probably.

I need to make sure to let the user chose https vs ssh.

And instead handle fork/branching via GitHub API.

Per #3 (comment)

• check for specific tags required for specific types of posts

Not all of these could be automated

e.g.

• R
• packages (e.g. use if YAML has package_version:, but also in some other cases)
• Software Peer Review (for pkg that passed peer review, or for use of dev guide)
• community (question: would we use this for posts written by at least one non-staff member? Currently #community tag is for many things - community-contributed package; unconf or similar community-oriented posts; community calls
• topic labels from software peer review submission OR tags = package categories from our Packages page

R markdown and markdown templates still show in my RStudio roblog addin but these functions were removed from roblog I think

reported by Kari Norman in ropensci-archive/roweb2#609 (comment)

Or an addin like the blogdown addin, to create the folder under content/technotes or content/blog and index.Rmd/index.md.

different from the function linting the post. There could be a wrapper for the two.

Hi @maelle!

This was my first time trying roblog::ro_blog_post_author(), and it couldn't find the template file. I'm not sure if this is because we changed the Blog Guide or roblog?

Thank you!

> roblog::ro_blog_post_author()
Error in `gh_process_response()`:
! GitHub API error (404): Not Found
✖ URL not found: <https://api.github.com/repos/ropensci-org/blog-guidance/contents/templates/author-file-template.md>
ℹ Read more at <https://docs.github.com/rest/reference/repos#get-repository-content>
Run `rlang::last_trace()` to see where the error occurred.

> rlang::last_trace()
<error/github_error>
Error in `gh_process_response()`:
! GitHub API error (404): Not Found
✖ URL not found: <https://api.github.com/repos/ropensci-org/blog-guidance/contents/templates/author-file-template.md>
ℹ Read more at <https://docs.github.com/rest/reference/repos#get-repository-content>
---
Backtrace:
    ▆
 1. └─roblog::ro_blog_post_author()
 2.   └─roblog:::get_tmpl("author-file-template.md")
 3.     └─gh::gh(...)
 4.       └─gh:::gh_process_response(raw)
Run rlang::last_trace(drop = FALSE) to see 3 hidden frames.

> devtools::session_info()
─ Session info ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.2.3 (2023-03-15)
 os       Ubuntu 22.04.2 LTS
 system   x86_64, linux-gnu
 ui       RStudio
 language en_CA:en
 collate  en_CA.UTF-8
 ctype    en_CA.UTF-8
 tz       America/Winnipeg
 date     2023-04-05
 rstudio  2023.03.0+386 Cherry Blossom (desktop)
 pandoc   2.19.2 @ /usr/lib/rstudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown)

─ Packages ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 package     * version date (UTC) lib source
 cachem        1.0.7   2023-02-24 [1] CRAN (R 4.2.3)
 callr         3.7.3   2022-11-02 [1] CRAN (R 4.2.2)
 cli           3.6.1   2023-03-23 [1] CRAN (R 4.2.3)
 crayon        1.5.2   2022-09-29 [1] CRAN (R 4.2.2)
 curl          5.0.0   2023-01-12 [1] CRAN (R 4.2.2)
 devtools      2.4.5   2022-10-11 [1] CRAN (R 4.2.2)
 digest        0.6.31  2022-12-11 [1] CRAN (R 4.2.2)
 ellipsis      0.3.2   2021-04-29 [1] CRAN (R 4.2.2)
 evaluate      0.20    2023-01-17 [1] CRAN (R 4.2.2)
 fastmap       1.1.1   2023-02-24 [1] CRAN (R 4.2.3)
 fs            1.6.1   2023-02-06 [1] CRAN (R 4.2.2)
 generics      0.1.3   2022-07-05 [1] CRAN (R 4.2.2)
 gh            1.3.1   2022-09-08 [1] CRAN (R 4.2.2)
 gitcreds      0.1.2   2022-09-08 [1] CRAN (R 4.2.2)
 glue          1.6.2   2022-02-24 [1] CRAN (R 4.2.2)
 htmltools     0.5.5   2023-03-23 [1] CRAN (R 4.2.3)
 htmlwidgets   1.6.1   2023-01-07 [1] CRAN (R 4.2.2)
 httpuv        1.6.8   2023-01-12 [1] CRAN (R 4.2.2)
 httr          1.4.4   2022-08-17 [1] CRAN (R 4.2.2)
 jsonlite      1.8.4   2022-12-06 [1] CRAN (R 4.2.2)
 knitr         1.42    2023-01-25 [1] CRAN (R 4.2.2)
 later         1.3.0   2021-08-18 [1] CRAN (R 4.2.2)
 lifecycle     1.0.3   2022-10-07 [1] CRAN (R 4.2.2)
 lubridate     1.9.2   2023-02-10 [1] CRAN (R 4.2.2)
 magrittr      2.0.3   2022-03-30 [1] CRAN (R 4.2.2)
 memoise       2.0.1   2021-11-26 [1] CRAN (R 4.2.2)
 mime          0.12    2021-09-28 [1] CRAN (R 4.2.2)
 miniUI        0.1.1.1 2018-05-18 [1] CRAN (R 4.2.2)
 pak           0.4.0   2023-01-15 [1] CRAN (R 4.2.2)
 pkgbuild      1.4.0   2022-11-27 [1] CRAN (R 4.2.2)
 pkgload       1.3.2   2022-11-16 [1] CRAN (R 4.2.2)
 prettyunits   1.1.1   2020-01-24 [1] CRAN (R 4.2.2)
 processx      3.8.0   2022-10-26 [1] CRAN (R 4.2.2)
 profvis       0.3.7   2020-11-02 [1] CRAN (R 4.2.2)
 promises      1.2.0.1 2021-02-11 [1] CRAN (R 4.2.2)
 promoutils    0.0.2   2023-04-05 [1] local
 ps            1.7.3   2023-03-21 [1] CRAN (R 4.2.3)
 purrr         1.0.1   2023-01-10 [1] CRAN (R 4.2.2)
 R6            2.5.1   2021-08-19 [1] CRAN (R 4.2.2)
 Rcpp          1.0.10  2023-01-22 [1] CRAN (R 4.2.2)
 remotes       2.4.2   2021-11-30 [1] CRAN (R 4.2.2)
 rlang         1.1.0   2023-03-14 [1] CRAN (R 4.2.3)
 rmarkdown     2.21    2023-03-26 [1] CRAN (R 4.2.3)
 roblog        0.1.0   2023-02-15 [1] Github (ropensci-org/roblog@cc3866e)
 rstudioapi    0.14    2022-08-22 [1] CRAN (R 4.2.2)
 sessioninfo   1.2.2   2021-12-06 [1] CRAN (R 4.2.2)
 shiny         1.7.4   2022-12-15 [1] CRAN (R 4.2.2)
 stringi       1.7.12  2023-01-11 [1] CRAN (R 4.2.2)
 stringr       1.5.0   2022-12-02 [1] CRAN (R 4.2.2)
 timechange    0.2.0   2023-01-11 [1] CRAN (R 4.2.2)
 urlchecker    1.0.1   2021-11-30 [1] CRAN (R 4.2.2)
 usethis       2.1.6   2022-05-25 [1] CRAN (R 4.2.2)
 vctrs         0.6.1   2023-03-22 [1] CRAN (R 4.2.3)
 xfun          0.38    2023-03-24 [1] CRAN (R 4.2.3)
 xtable        1.8-4   2019-04-21 [1] CRAN (R 4.2.2)
 yaml          2.3.7   2023-01-23 [1] CRAN (R 4.2.2)

 [1] /home/steffi/R/x86_64-pc-linux-gnu-library/4.2
 [2] /usr/local/lib/R/site-library
 [3] /usr/lib/R/site-library
 [4] /usr/lib/R/library

If the blog post is about an onboarded package then the user could supply the onboarding issue number and some fields could be filled automatically (even a few template lines in the end with <edit me, thank your reviewers here if you haven't done that in the rest of the post>, also something corresponding to "consider ending by pointing to open issues that readers might work on")

For that have a look at the post header, find whether it was Rmd knit to md, in which case we do not expect Hugo shortcodes for images.

A mistake I am constantly making, is missing the / at the front of internal links like /blog/2022/08/09/working-with-qualtrics-data-excluding/.

Could this be added to the url checks?

I.e. page bundles or not.

Change links in roweb2 README / wherever the blogging guidance lives at that point.

Acknowledge reviewers by listing their full name, linked to their online presence, such as GitHub, Twitter, or personal website. Link to software peer review thread for your package.

• whoami::fullname()

• whoami::gh_username()

• Sys.getenv("ORCID_ID") (which is what desc uses for ORCID ID guessing cf ?desc::desc_add_me.

Input: path to .md blog post.

What it'd do:

• spell check,

• checking there is an alt text by figure (and indicating to use fig.cap otherwise),

• checking the links (relative links, actual URLs with crul::ok)

• if possible checking the functions are function()

Digest other stuff from https://r-resources.massey.ac.nz/rmarkdown/ in the function and put the rest in guidelines in the README of this repo.

We should discuss what goes in the checklists https://github.com/ropenscilabs/roblog/blob/master/inst/checklists/submission-checklist.csv

especially to decide how short or long the checklist needs to be. Maybe the editor's checklist should be the long one, with one item per post component.

I suggest adding this:
I have read the Technical Guidelines.

cf ropensci-archive/roweb2#578

Here's how Hugo does it https://github.com/gohugoio/hugo/blob/21ca2e9ce4255bfad2bb0576aff087a240acf70a/parser/pageparser/pagelexer_shortcode.go#L83

Input: Path to Markdown post

function creating the excerpt and URL for the discuss post (easy to create that URL from info in the YAML)

https://github.com/ropensci/roweb3/blob/main/scripts/newsletter/newsletter-xml.R

RStudio R Markdown blog post template has # Section and ## Subsection. Best to change to ### Section and #### Subsection or whatever is appropriate

https://webaccess.berkeley.edu/ask-pecan/click-here

Looks like you get these from same source, but noting here just in case. Ok to close this issue if no roblog update needed.

In this PR, changed YAML description to add length. description: "A very short summary of your post (~ 100 characters)"

During my practice in creating a dummy blog post, I ran into the following output when I ran ro_check_urls() on my dummy blog post (available here)

> roblog::ro_check_urls("content/blog/2020-02-28-weathercan-dummy/index.md")
Unknown option: verb
Unknown option: verb
Unknown option: verb
Unknown option: verb
Unknown option: verb
Possibly broken URLs: https://www.tidyverse.org, http://github.com/ropensci/weathercan, 
http://climate.weather.gc.ca/historical_data/search_historic_data_e.html, 
http://dplyr.tidyverse.org/, https://www.tidyverse.org.

The links are not broken, though, and I think the "Unknown option: verb" reflects a problem with the crul::ok() function, but that's where I stopped my investigation.

In case this is related to package versions:

> devtools::session_info()
─ Session info ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 setting  value                       
 version  R version 3.6.2 (2019-12-12)
 os       Ubuntu 18.04.3 LTS          
 system   x86_64, linux-gnu           
 ui       RStudio                     
 language en_CA:en                    
 collate  en_CA.UTF-8                 
 ctype    en_CA.UTF-8                 
 tz       America/Winnipeg            
 date     2020-02-27                  

─ Packages ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 package     * version date       lib source                              
 assertthat    0.2.1   2019-03-21 [1] CRAN (R 3.5.3)                      
 backports     1.1.5   2019-10-02 [1] CRAN (R 3.6.1)                      
 callr         3.4.1   2020-01-24 [1] CRAN (R 3.6.2)                      
 cli           2.0.1   2020-01-08 [1] CRAN (R 3.6.2)                      
 clisymbols    1.2.0   2017-05-21 [1] CRAN (R 3.5.1)                      
 commonmark    1.7     2018-12-01 [1] CRAN (R 3.5.2)                      
 crayon        1.3.4   2017-09-16 [1] CRAN (R 3.5.1)                      
 crul          0.8.4   2019-08-02 [1] CRAN (R 3.6.1)                      
 curl          4.3     2019-12-02 [1] CRAN (R 3.6.1)                      
 desc          1.2.0   2018-05-01 [1] CRAN (R 3.5.1)                      
 devtools      2.2.1   2019-09-24 [1] CRAN (R 3.6.1)                      
 digest        0.6.24  2020-02-12 [1] CRAN (R 3.6.2)                      
 dplyr         0.8.4   2020-01-31 [1] CRAN (R 3.6.2)                      
 ellipsis      0.3.0   2019-09-20 [1] CRAN (R 3.6.1)                      
 fansi         0.4.1   2020-01-08 [1] CRAN (R 3.6.2)                      
 fs            1.3.1   2019-05-06 [1] CRAN (R 3.6.0)                      
 gh            1.1.0   2020-01-24 [1] CRAN (R 3.6.2)                      
 glue          1.3.1   2019-03-12 [1] CRAN (R 3.5.2)                      
 httpcode      0.2.0   2016-11-14 [1] CRAN (R 3.5.1)                      
 httr          1.4.1   2019-08-05 [1] CRAN (R 3.6.1)                      
 jsonlite      1.6.1   2020-02-02 [1] CRAN (R 3.6.2)                      
 magrittr      1.5     2014-11-22 [1] CRAN (R 3.5.1)                      
 memoise       1.1.0   2017-04-21 [1] CRAN (R 3.5.1)                      
 packrat       0.5.0   2018-11-14 [1] CRAN (R 3.5.1)                      
 pillar        1.4.3   2019-12-20 [1] CRAN (R 3.6.2)                      
 pkgbuild      1.0.6   2019-10-09 [1] CRAN (R 3.6.2)                      
 pkgconfig     2.0.3   2019-09-22 [1] CRAN (R 3.6.1)                      
 pkgload       1.0.2   2018-10-29 [1] CRAN (R 3.5.1)                      
 praise        1.0.0   2015-08-11 [1] CRAN (R 3.5.1)                      
 prettyunits   1.1.1   2020-01-24 [1] CRAN (R 3.6.2)                      
 processx      3.4.1   2019-07-18 [1] CRAN (R 3.6.1)                      
 ps            1.3.0   2018-12-21 [1] CRAN (R 3.5.2)                      
 purrr         0.3.3   2019-10-18 [1] CRAN (R 3.6.1)                      
 R6            2.4.1   2019-11-12 [1] CRAN (R 3.6.1)                      
 Rcpp          1.0.3   2019-11-08 [1] CRAN (R 3.6.1)                      
 remotes       2.1.0   2019-06-24 [1] CRAN (R 3.6.1)                      
 rlang         0.4.4   2020-01-28 [1] CRAN (R 3.6.2)                      
 roblog        0.1.0   2020-02-21 [1] Github (ropenscilabs/roblog@9966673)
 rprojroot     1.3-2   2018-01-03 [1] CRAN (R 3.5.1)                      
 rstudioapi    0.11    2020-02-07 [1] CRAN (R 3.6.2)                      
 sessioninfo   1.1.1   2018-11-05 [1] CRAN (R 3.5.2)                      
 stringi       1.4.6   2020-02-17 [1] CRAN (R 3.6.2)                      
 stringr       1.4.0   2019-02-10 [1] CRAN (R 3.5.2)                      
 testthat      2.2.1   2019-07-25 [1] CRAN (R 3.6.1)                      
 tibble        2.1.3   2019-06-06 [1] CRAN (R 3.6.0)                      
 tidyselect    1.0.0   2020-01-27 [1] CRAN (R 3.6.2)                      
 triebeard     0.3.0   2016-08-04 [1] CRAN (R 3.5.1)                      
 urltools      1.7.3   2019-04-14 [1] CRAN (R 3.6.0)                      
 usethis       1.5.1   2019-07-04 [1] CRAN (R 3.6.1)                      
 withr         2.1.2   2018-03-15 [1] CRAN (R 3.5.1)                      
 xml2          1.2.2   2019-08-09 [1] CRAN (R 3.6.1)                      

[1] /home/steffi/R/x86_64-pc-linux-gnu-library/3.6
[2] /usr/local/lib/R/site-library
[3] /usr/lib/R/site-library
[4] /usr/lib/R/library

When one uses spelling there's a way to ignore words (e.g. rOpenSci is not a typo). Where do we keep the words list and how do we update it?

In roweb2? And the PR adding a blog post would also add new exceptions?

Not compulsory in any case.

Useful as a suggestion.

And useful to remind authors to have big text.

The R Markdown post template begins with a large code chunk to define knitr hooks. Would it be convenient to wrap those hooks in an roblog function?

Preferably agnostic to Hugo / Quarto.

https://twitter.com/MikeMahoney218/status/1546589306550198273

No plan to do that now but wanted to track this as seeing #39 reminded me of it.

@mikemahoney218

Like lintr. Idea by @richfitz.

Alignment, size etc.

Cf ropensci-archive/roweb2#551 (comment)

While netlify was preparing the preview for an upcoming blog post, I noticed multiple warnings about mixed content (resources such as images fetched over HTTP while the website is HTTPS).

I will check and submit a PR to roweb2 to fix it wherever possible but it would be useful to add a check to try and prevent this in the future.

There are many pitfalls about programmatically checking if a website supports HTTPS but in a case of a single image, I think a curl call should work.

An idea for a helper function:

Function would take a publication date and slug name, then create the folder in content/blog and a start a draft date-slug.Rmd or date-slug.md file in that folder from the template?

I am a bit lazy and finding the long path to "content/blog/post/index.Rmd" is sometimes too much (I am spoiled from devtools::test() and similar functions that know how to find the files).

Maybe roblog could use rstudioapi::getActiveDocumentContext to fill it up ro_check_urls() and ro_lint_md() if rstudioapi detects Rstudio and the path is missing. Most of the contributors only edit one post per contribution so I'm not sure if it is worth it but, I thought it would be nice to brought it up.

Took my first look at roblog and trying to use it to submit a draft post.

Context: I'm now fairly comfortable with my workflow based on these instructions except that I work on a branch, not a fork. I use those instructions to guide first-time post submitters. I'm not yet comfortable/versatile with diverging from that workflow, whereas someone who has had a package go through onboarding won't have the same perceptions. I use RStudio just once in a while while trying to learn stuff and don't yet fully get "project" setup etc

• what does roblog aim to make simpler/better for an author of a blog post or tech note compared with the current instructions? Can you add that statement near top of README?
• I was able to follow https://github.com/ropenscilabs/roblog#r-markdown-templates to create a blog post template (...after starting new session 🤪)
• my habit in trying a thing for the first time is to scan the README then start executing things from the top. After scanning, I wasn't sure what my minimal starting materials had to be
  • e.g. do I start with creating a new blog post R Markdown template in RStudio? but maybe I should create a post project first? or do I set up my directories to suit Fork helper so my files are in the right place?
• Tried Create a post project. I wasn't convinced I needed a post draft for that.
  • Error in create_post_project(tempdir(), "test", "2018-10-15", type = "Rmd", : could not find function "create_post_project"

@stefaniebutland

All guidance lives in Rmd in vignettes

The structure of the navbar is defined in the pkgdown config

The post examples used in this section of the content guidelines are stored in a YAML file (not the final list, you'll have to amend it). The page is generated using the YAML so if one amends the YAML, Jeroen's system re-builds the docs website and the checklists page is then up-to-date.

Both checklists that you see in the checklists page (general items, items for peer reviewed packages) are stored in csv files. The checklist page is generated using the csv so if one amends the CSV, Jeroen's system re-builds the docs website and the checklists page is then up-to-date.

https://matt-dray.github.io/altcheckr/

a function for scanning the text for packages names to add links to their website. Or even an add-in to add the link for a selected package name. For rOpenSci packages (we want to link other packages as well of course) the website could be derived from the CodeMeta file. For other packages probably METACRAN.

Inputs:

• slug

• date

An Rproj

• named after the slug

• using the date and slug in the template

• using whoami to fill the name.

• mayyybe one day using rorcid to retrieve the first URL if there's an ORCID_ID environment variable.

Inputs

• Path of the folder where the blog post (Markdown) lives

• slug

• date

• Path of the local clone of roweb2

• technote vs blogpost (or read that from the Markdown?)

• When git2r works for Windows (at the moment I use add_my_content and push from a command line)

• Gather feedback from users of other OS who can try to use push=TRUE.

• Add a minimal git2r version to DESCRIPTION.

Too many false positives

ro_lint_md() identifies problems with sub headings that have extra punctuation (i.e. ?, -, /) and identifies this as a problem with sentence case.

For example, the headings...

• "Accessible highlighting?" is suggested to be "Accessible highlighting"
• "Server-side syntax highlighting" is suggested to be "Server side syntax highlighting"
• "Produce line-highlighted code blocks with glue/paste0" is suggested to be "Produce line highlighted code blocks with glue paste0"