rpackagereadmevignette

Link to vignette from readme.rda

I am building an R package. I have several vignettes that I would like to include links to in my README.Rmd.

I know that vignettes are to be built optionally when installing the package.

I do not really understand where I should start. I am in the process of building the package in R studio. I would the user to be able to see the vignette just by clicking at link in the readme on GitHub. Is this possible? How?

The following obviously does not work. 

[The main vignette](vignettes/Vignette.html)
Solution

  • NOTE: see below for an easier way to do this.

    You can do this, but it might be more trouble than it's worth.

    The problems are

    1. Your package directories are different in the source on Github than they are when your package is installed in R. The link you give would be fine if you actually put Vignette.html in the vignettes directory, but when your package is installed, it will be in doc.

    2. RStudio won't put the processed vignette in either of those locations by default if you just knit Vignette.Rmd.

    3. You don't normally commit output files on Github.

    So here's what you could do to work around this. Make the link look like

    [The main vignette](doc/Vignette.html)

    To make sure that file is there on Github, in RStudio create the doc directory and run

    rmarkdown::render("vignettes/Vignette.Rmd", output_file="doc/Vignette.html")

    You'll need to commit the output file and push it to Github, but you don't want to include it when you build the .tar.gz file, so you'll also need to add the lines

    ^doc$
^doc/Vignette.html$

    to the .Rbuildignore file in the main package directory.

    With all these changes I think your vignette will be visible on Github and also after you install the package in R.

    A much simpler approach is just to tell the user to run

    vignette("Vignette", package = "yourpackagename")

    after installing the package, but this won't make it visible on Github.

    EDITED to update:

    I wrote the answer above in 2019. In 2023 it is much easier. Use pkgdown to create a web site for your package, and link to that from your README. You will have the choice of linking to a released version of the vignette (by convention you create this after CRAN accepts your package) or to a development version (which you normally update every time you commit a change to the main branch). Instructions for pkgdown are here: https://pkgdown.r-lib.org/ .