Best practice to have package vignette available as HTML (or PDF) on GitHub?

I am developing a rather niche R package that is available on GitHub but with no immediate intention to make it available on CRAN.

A vignette is available, so I suggest that users install the package with devtools::install_github("jhchou/medianeffect", build_vignettes = TRUE), which works fine once the package is installed.

However, I would like the vignette available to view even without installing the package. With such a niche product, having the vignette available might help people find and understand the use of the package.

Is there a recommended best practice for making the built vignette available as an HTML file without package installation?

One idea I considered was leaving ^doc$ in the .Rbuildignore file, but removing doc from the .gitignore file. I presume this would allow the contents of the doc directory, which includes the built HTML version of the vignette, to be available on GitHub, but would not interfere with the package build process. Is this correct, or a good idea?

A somewhat similar question was posted in this post, but didn't address my question.

The process you describe - having the /doc directory checked in, but ignored on build - seems plausible.

One thing you should be aware of is that GitHub does not quite like serving HTML files - it will show the source file, but it will refuse to render the file in browser. This seems to be intentional behaviour, as the GitHub guys consider themselves to be in the source code business, and not static website business.

There are tools around to sidestep the issue, one that I like is http://raw.githack.com/

Have you considered using pkgdown to build a web page for your package using the documentation and vignette you already provide? this can even be automated using Travis CI or Github Actions.

2 Likes

@rstub solution is optimal (and not difficult to implement). Many packages on github are using pkgdown. If you didn't want to go that route you could extend your readme.md to include the vignette. You need to use usethis::use_readme_rmd which creates an rmd that is knitted into a md. The benefit is that you can use code chunks, just like the vignette.

eg. of package down + use_readme_rmd (https://usethis.r-lib.org/reference/use_readme_rmd.html)

1 Like