install_github: Install a package with injected HTML in the help file

In jonocarroll/btts: We need to go... Back To The Source

Description

Behaviour is otherwise identical to install_github except that some HTML code is carefully inserted in the roxygen2 header. Processing of the roxygen2 code into a .Rd help file is also hijacked and HTML sanitisation is deactivated (for that call only). The injected HTML (static, not user-changeable for now) overlays a pull-up tab at the bottom of HTML help files (such as viewed in RStudio) with some context of the GitHub package, such as links to the source, issues page, version, and author.

Usage

install_github(repo, username = NULL, ref = "master", subdir = NULL,
  auth_token = devtools:::github_pat(quiet), host = "api.github.com",
  force = TRUE, quiet = FALSE, ...)

Arguments

repo	Repository address in the format username/repo[/subdir][@ref|#pull]. Alternatively, you can specify subdir and/or ref using the respective parameters (see below); if both are specified, the values in repo take precedence.
username	User name. Deprecated: please include username in the repo
ref	Desired git reference. Could be a commit, tag, or branch name, or a call to github_pull. Defaults to "master".
subdir	subdirectory within repo that contains the R package.
auth_token	To install from a private repo, generate a personal access token (PAT) in https://github.com/settings/tokens and supply to this argument. This is safer than using a password because you can easily delete a PAT without affecting any others. Defaults to the GITHUB_PAT environment variable.
host	GitHub API host to use. Override with your GitHub enterprise hostname, for example, "github.hostname.com/api/v3".
force	whether to force installation of dependencies even if their SHA1 reference hasn't changed from the currently installed version.
quiet	if TRUE suppresses output from this function.
...	Other arguments passed on to install.

Details

The code for *that* function is linked to in the GitHub repo, meaning you can see exactly how the function was written, rather than the comment-lacking body() from within R.

It is advisable to install the package for the first time using 'devtools::install_github' so that dependencies are properly met. The additional functionality can then be added by re-installing with 'btts::install_github'.

Warnings This function has potential to make damaging changes to your R library, and should not be executed on production or mission-critical setups. You are invited to carefully scrutinize the source code http://github.com/jonocarroll/btts to ensure that nothing malicious is being done here.

Because this function needs to unload the namespace of the package it is trying to reinstall, it is a *very* good idea to start with a fresh session before using this function. In RStudio, CTRL/CMD + F10 restarts the session.

Limitations

This function is not currently able to install GitHub packages that it itself depends on (for now, RCurl, gtools, and itself). Doing so results in failure to re-load the namespace and that's not good. This of course means that it can't self-document with the injected HTML.

The full consequences of changing the default parameters has not been explored. Most of the code for this function calls devtools functions, but there is no guarantee attached to any of it.

If something goes wrong

If you do find a bug that causes something to go wrong, please file an Issue on GitHub. Some steps to try and remedy the failure that I've found to work include

• Restarting the R session and trying again,

• Manually removing the offending package with (utils::remove.packages),

• Manually deleting the library folder for the offending package,

• Installing the GitHub or CRAN version of the package with the standard tools, (i.e. utils::install.packages or devtools::install_github).

Acknowledgements

Noam Ross created https://github.com/noamross/htmlhelp which I adapted into this form. This would not have been possible without his first steps.

References

http://github.com/jonocarroll/btts

Examples

## Not run: 
install_github("jonocarroll/butteRfly")

## End(Not run)

jonocarroll/btts documentation built on May 24, 2019, 2:49 p.m.