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

In jonocarroll/githubtools: Tools for building and using GitHub pkgs.

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	Force installation even if the git SHA1 has not changed since the previous install.
quiet	if TRUE suppresses output from this function.
...	Other arguments passed on to install.

Details

Warning 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/githubtools to ensure that nothing malicious is being done here.

Limitations

This function is not currently able to install GitHub packages that it itself depends on. 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).

References

http://github.com/jonocarroll/githubtools

Examples

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

## End(Not run) 

jonocarroll/githubtools documentation built on May 19, 2019, 7:31 p.m.