User feedback on documentation

[krlmlr]

r-lib/styler#981 (comment)

[maelle]

One of the problems identified is that the description of what finalize_version() does, is wrong in usage.Rmd.

To keep it up-to-date with the truth, I'm looking into tools::parse_Rd().

[maelle]

Also relevant https://github.com/yihui/printr/blob/master/R/help.R

[maelle]

library("magrittr")

db <- tools::Rd_db("fledge")
Rd <- db$finalize_version.Rd
Rd[which(unlist(lapply(Rd, attr, 'Rd_tag')) != "\\description")] <- NULL
temp_file <- withr::local_tempfile()
description <- tools::Rd2txt(Rd, fragment = TRUE, out = temp_file) %>% 
  readLines()
description <- paste0(description[3:length(description)], collapse = "\n")
cat(description)
#>      Calls the following functions:
#> 
#>        1. 'commit_version()'
#> 
#>        2. 'tag_version()', setting 'force = TRUE' if and only if
#>           'commit_version()' amended a commit.
#> 
#>        3. Force-pushes the created tag to the '"origin"' remote, if
#>           'push = TRUE'.


db <- tools::Rd_db("fledge")
Rd <- db$bump_version.Rd
Rd[which(unlist(lapply(Rd, attr, 'Rd_tag')) != "\\description")] <- NULL
temp_file <- withr::local_tempfile()
description <- tools::Rd2txt(Rd, fragment = TRUE, out = temp_file) %>% 
  readLines()
description <- paste0(description[3:length(description)], collapse = "\n")
cat(description)
#>      Calls the following functions:
#> 
#>        1. Verify that the current branch is the main branch.
#> 
#>        2. Check if there were changes since the last version.
#> 
#>        3. 'update_news()'
#> 
#>        4. 'update_version()', using the 'which' argument
#> 
#>        5. Depending on the 'which' argument:
#> 
#>             • If '"dev"', 'finalize_version()' with 'push = FALSE'
#> 
#>             • Otherwise, 'commit_version()'.

^{Created on 2022-08-25 by the reprex package (v2.0.1)}

[krlmlr]

Do we need to act here?

[maelle]

I think that once we tackle other documentation labelled issues, we should re-read the feedback to ensure we've improved docs enough.

[D3SL]

I self-host Gitea and ran into two issues. First fledge is hardcoded to use origin as the remote's name, and second I didn't have a value for init.defaultbranch set globally at all.

For now I think this section critically needs an update to account for those:

Your package needs to have a remote that indicates the default branch (e.g. GitHub remote) or to be using the same default branch name as your global/project init.defaultbranch.

[maelle]

@D3SL thanks for your feedback! Would you like to make a PR to the docs?

[maelle]

Related: #112

[D3SL]

@maelle would that be setup.rmd or readme.md? Also this may be something that should be fixed on Fledge's side, not sure if you want to change the documents then have to change them back again.