milesmcbain / rmdocs

browse help files as Rmarkdown documents

rmdocs

Browse help files as RMarkdown source documents.

Installation

# install.packages("devtools")
devtools::install_github("milesmcbain/rmdocs")

Usage

rmdocs::rmd_help(help)

Use option rmd_doc_width to control the text width of the documentation output. Defaults to 80.

Replacing help and ?

So in love with Rmd help that you can’t imagine it any other way? I HEAR you. If you call library(rmdocs) Rmarkdown generating replacements for utils::help and utils::? will be loaded into your session. Avoid the library call if you don’t want that.

VSCode

In keybindings.json, assuming you have {rstudioapi} emulation enabled:

[
    {
        "description": "Rmd helpfile for object",
        "key": "ctrl+shift+h",
        "command": "r.runCommandWithSelectionOrWord",
        "args": "rmddocs::rs_rmd_help()",
        "when": "editorTextFocus"
    },
]

RStudio

Bind the addin ‘Rmarkdown help() on object’ to a choice keyboard shortcut and away you go.

rmdocs's Issues

Error in gsub("(\\r?\\n\\r?\\n)([A-Z].*)(?<=:)(\\r?\\n\\r?\\n)", "\\1### \\2\\3", : input string 1 is invalid UTF-8

I get the following errors:

> rmdocs::rmd_help(help)
Error in gsub("(\\r?\\n\\r?\\n)([A-Z].*)(?<=:)(\\r?\\n\\r?\\n)", "\\1### \\2\\3",  : 
  input string 1 is invalid UTF-8
> rmdocs::rmd_help('help')
Error in rmdocs::rmd_help("help") : Couldn't find help for "help"
> rmdocs::rmd_help(mean)
Error in gsub("(\\r?\\n\\r?\\n)([A-Z].*)(?<=:)(\\r?\\n\\r?\\n)", "\\1### \\2\\3",  : 
  input string 1 is invalid UTF-8
> rmdocs::rmd_help('mean')
Error in rmdocs::rmd_help("mean") : Couldn't find help for "mean"

If I change lines 16 & 17 of rmd_help I can stop the error and get the function to open an unrendered rmd file:

with_headings <- gsub("(\\r?\\n\\r?\\n)([A-Z].*)(?<=:)(\\r?\\n\\r?\\n)", 
                        "\\1### \\2\\3", encodeString(help_file), perl = TRUE)

I haven't set any help options, and the following are the help-related options settings (however, I do have the problem where if I am editing an internal package R Studio is no longer able to render the development version of the help docs, I just get internal server error 500):

$help.search.types
[1] "vignette" "demo"     "help"    

$help.try.all.packages
[1] FALSE

$help_type
[1] "html"

Session info:

> sessionInfo()
R version 4.0.5 (2021-03-31)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows Server x64 (build 17763)

Matrix products: default

locale:
[1] LC_COLLATE=English_Australia.1252  LC_CTYPE=English_Australia.1252    LC_MONETARY=English_Australia.1252
[4] LC_NUMERIC=C                       LC_TIME=English_Australia.1252    

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

loaded via a namespace (and not attached):
 [1] fansi_0.5.0     utf8_1.2.1      crayon_1.4.1    rmdocs_0.0.1    R6_2.5.0        lifecycle_1.0.0 magrittr_2.0.1 
 [8] pillar_1.6.1    rlang_0.4.11    fs_1.5.0        vctrs_0.3.8     ellipsis_0.3.2  tools_4.0.5     readr_1.4.0    
[15] hms_1.1.0       compiler_4.0.5  pkgconfig_2.0.3 tibble_3.1.2    

compatibility with devtools shims

can't currently make rmd help for dev help loaded with devtools::load_all()

rstudio-agnostic version

Hi there,
after our conversation on twitter I had to try my hands at this.
Under https://github.com/jmbuhr/rmdocs/tree/lsp-mode I have a hacky first implementation of a rstudio-agnostic version of rmdocs that can work with e.g. (neo)vim as well.

Instead of relying on rstudio get the function-name of interest and open the file, the function rmd_help now takes a string and returns a filepath if lspmode == TRUE)

You can then create a function (potentialy a simple nvim plugin) to execute rmd_help and open the file in a new tab. Right now it just uses the word under the cursor, but it would be much more elegant to tap into the lsp's knowledge of the symbols in the future.

Example code to put in init.vim:

fun! Rmdocs()
  let l:topic = expand("<cword>")
  echo l:topic
  let l:command = "R --vanilla -q --no-echo -e 'rmdocs::rmd_help(\"" . l:topic . "\", lspmode = TRUE)'"
  let l:path = system(command)
  :execute 'tabnew' l:path
endfun

map <leader>hr :call Rmdocs()<cr>

backport for `tools::R_user_dir()`?

I'm back on R 3.6 and can't install {rmdocs} since it uses tools::R_user_dir(). Any chance of backporting this function or do I need to bite the bullet and update?

rmd_help could return generated file path invisibly?

Would be useful if you want to build an automation on top of rmd_help that knits the file.

fix timezone bug

  old_files <- as.numeric(Sys.Date() - as.Date(file_info_df$birth_time, tz = Sys.timezone())) > 0

use {atcursor} for rstudio addin