How to add vignette.html (or .R) files to a github-rep

Package development
1

After using the function "devtools::build_vignettes() " the vignette .html and .R files are created and stored in the folder "doc". However, this folder does not exist on the github repository, which reports only the folder "vignettes" containing the .Rmd files. How do I add the .html files built with "build_vignettes" to the github repository, so that users can download the package and the available vignettes files?

2

hi @VittorioFortino

As I know, you don't need to build your vignettes before build.

If you use the workflow describe by Hadley and Jennifer in there book, users will have the vignettes

bulid_vignettes use the same algorithm that build does. So if you or users build the packages they will have the vignettes

Hope it help

1 Like
3

Users who install from github will not have the vignettes by default:

Similarly, devtools::install_github() (and friends) will not build vignettes by default because they’re time consuming and may require additional packages. You can force building with devtools::install_github(build_vignettes = TRUE) . This will also install all suggested packages.

1 Like
4

I followed the instructions. But is there a way to link the R package to a pre-built vignette.html/pdf file?

5

devtools::install_github(...,build_vignettes = TRUE) ..does not build the vignette. Is it possible that there is something wrong with the ".Rbuildignore"?

6

It works for me, with my package kayadata:

remotes::install_github("jonathan-g/kayadata", build_vignettes = TRUE, force = TRUE)

builds the vignette.

remotes::install_github("jonathan-g/kayadata", build_vignettes = FALSE, force = TRUE)

installs the package, but without the vignette.

I use the force argument to force reinstalling with different parameters so I can test the differences (by default install_github will not re-install if the package was already installed from a git commit with the same hash value, so if you have the package installed and then run remotes::install_github('foo/bar', build_vignettes=TRUE), it will not reinstall the package and thus will not build the vignettes. If you add force = TRUE to the arguments, then it will force a reinstall and build the vignettes.

7

Here is my workflow for my packages with vignettes on GitHub that I develop on RStudio. I'm assuming you in the situation where you don't want user to have to rebuild your vignettes when installing from GitHub. Mine for example would take forever to build and depend on many packages (in Suggests) that I would never want users to have to install.

That means I want all my vignette files in the inst/doc folder in my GitHub package repo. The originals are in the vignettes folder.

devtools::build_vignettes() is going to rebuild your vignettes but put them at the base level in doc which is not where you need them. It will also create the Meta folder which you don't need.

devtools::build() will make a tar.gz file with the vignette files in inst/doc but you don't want the tar.gz for your GitHub package repo. You want the inst/doc folder filled with the vignette files.

I use this code when I have changed my vignettes and need to update them in a GitHub package repo:

tools::buildVignettes(dir = ".", tangle=TRUE)
dir.create("inst/doc")
file.copy(dir("vignettes", full.names=TRUE), "inst/doc", overwrite=TRUE)

Then push the changes to GitHub. Also this will mean that when you use Install and Restart on the Build tab, your vignettes will now be there too.

Be aware that RStudio's default Check package behavior on the Build tab is to delete your inst/doc folder. If you don't notice and push changes to GitHub, you've just deleted all your vignettes from your GitHub package. They are still there in the vignettes folder but you'd have to use the build_vignettes=TRUE in install_github() to see them. The deletion is happening because you need to use devtools:check(vignettes=FALSE) and there is no way to set that from the Build Options in RStudio. But you can uncheck the use devtools package functions and stop RStudio from using devtools. You may want to add --no-manual to the R CMD check options box since building the manual can be time consuming.

1 Like
8

A workflow that's easier for users is to provide the vignettes in a pkgdown website so that they can browse it online, with the rest of the documentation. As a developer you can use Travis/GitHub Actions/etc to update the pkgdown website and keep it in sync with your package source without having to remember that.

Of course this makes them reliant on a working internet connection so that's not an actual workaround for build_vignettes=TRUE. :slightly_smiling_face:

A bit more on vignettes workflow on the R-hub blog.

1 Like