I am a little confused as to why there are multiple possible locations for "vignettes" in an R package. I don't understand which locations are used for what and when. For example:
devtools::use_vignettes()
creates a vignettes folder under the root of the package
devtools::build_vignettes()
creates a inst/doc folder that gets promoted to the root at build
pkgdown::build_site()
creates a docs folder.
As background:I have read H.Wickhams R packages book and I have created several packages using the first option and all things have behaved well. I would have users install from github using:
devtools::install_github(pkg,build_vignettes=TRUE)
Now, I have just started to contribute in the joint development of a package in which the first and third option have been used. I have noticed that the .rmd file in the vignettes folder is the same as the index.html file in the docs folder. Does pkgdown copy from the vignettes folder?
Also for this package when i install from github (with build_vignettes=TRUE) i get an error saying installation failed because the doc/index.html path couldn't be found. Now why would that happen?
Vignettes development
There is only one place to put raw vignettes, it is in the vignette directory at the root. This is the place where you write your Rmd file with text and code examples, when developing your package.
Build vignettes for your users
When you build your vignettes, the Rmd file will be knit. The resulting html file, the raw Rmd file and the extraction of the R code will be three files saved in the inst/doc directory. This is what will be kept in the package installation. This is what users will be able to read.
{pkgdown}
{pkgdown} is using your Rmd files of the vignette directory to knit html files so that it can build a website for your package. It also build a page for the list of functions and a index from the Readme file that is also used for your git repository. This is not supposed to stay in the R package, and not accessible to the users. This is to present your package on the Internet.
Conclusion
Hence, when you develop, you only write your Rmd vignette in the vignette directory. The others will automatically keep what they need.
Related
I have created a package in R. It is all fully documented and written according to R package guidelines. I have used devtools to generate documentation.
document("/home/rstudio/EndoMineR/")
However when I try to use ?EndoMineR I get the error:
No documentation for ‘EndoMineR’ in specified packages and libraries:
you could try ‘??EndoMineR’
How can I create the help files for my package? What am I likely to be missing?
As additional information, when I click the package name in R studio I get the help files but not if I try ?EndoMineR. Also the .Rd files in the man directory (which I think is what devtools::document() generates) seem to be updating just fine. I assume the ?EndoMiner accesses the man files so I'm not sure why this folder is not accessible (it is top level)
My package is hosted in github, and user can install it through devtools::install_github.
Now I'm using pkgdown to generate documentation site, which created a 10M docs folder. Then I found devtools::install_github always download the whole master zip ball which become quite slow.
I tried to exclude the docs folder with these attempts:
.Rbuildignore, turned out it's only about bundled package, while install_github is installing source package so it doesn't work.
put package in pkg folder, put the generated docs folder out of pkg folder. However the whole master zip ball is always downloaded, even with subdir = "pkg" specified.
put development in a branch, and to create a special package branch without docs folder. Merge two branch but let package branch exclude docs folder. I tried make .gitignore to be branch specific but it doesn't seem to work. This seemed to be impossible.
My newest attempt is to create a separate repo solely for the website, just let pkgdown create the website in that folder like build_site(path = "../docsite/docs"). This should solve the problem and is simple and clean. The only imperfection is the website url will not be the usually pattern.
EDIT: with the latest version of pkgdown, there is no path parameter anymore, you need to specify it in the site configuration yaml, which works better (you don't need to specify it in every command).
I used packrat (v 0.4.8.-1) to to create a snapshot and bundle of the R package dependencies that go along with the corresponding R code. I want to provide the R code and packrat bundle to others to make the work I am doing (including the R environment) fully reproducible.
I tested unbundling using a different computer from the one I used to write R code and create the bundle. I opened an R code file in R studio, and called library(packrat) to load packrat (also v 0.4.8-1). I then called packrat::unbundle(bundle = "directory", where = "directory"), which unbundled successfully. But subsequently calling packrat::restore() gave me the error "This project has not yet been packified. Run 'packrat::init()' to init packrat". It seems like init() should not be necessary because I am not trying to create a new snapshot, but rather utilize the one in the bundle. The packrat page (https://rstudio.github.io/packrat/) and CRAN provide very little documentation about unbundling to help troubleshoot this, or that I could point users of my code to for instructions (who likely will be familiar with R, but may not have used packrat).
So, can someone please provide clear step-by-step instructions for how users of a bundled snapshot should unbundle, and then use that saved snapshot to run a R code file?
After some experimenting, I found an approach that seems to have worked so far.
I have provided users with three files:
-tar.gz (packrat bundle file)
-unbundle.R (R code file that includes a library statement to load
the packrat library, and the unbundle command for the tar.gz file)
-unbundle_readme.txt
The readme file includes instructions similar to those below, and so far users have been able to run R code using the package dependencies. The readme file tells users about requirements (R, R studio, packrat, R package development prerequisites (Rtools for Windows, XCode for Mac)), and includes output of sessionInfo() to document R package versions that the R code should use after instructions are followed. In the example below 'code_folder' refers to a folder within the tar.gz file that contains R. code and associated input files.
Example unbundle instructions:
Step 1
Save, but do not expand/unzip, the tar file to a directory.
Problems with accessing the saved package dependencies
are more likely when a program other than R or R studio
is used to unbundle the tar file.
If the tar file has already been expanded, re-save the
tar file to a new directory, which should not be a the same
directory as the expanded tar file, or a subdirectory of
the expanded tar file.
Step 2
Save unbundle.R in the same directory as the tar file
Step 3
Open unbundle.R using R studio
Step 4
Execute unbundle.R
(This will create a subfolder ‘code_folder’.
Please note that this step may take 5-15 minutes to run.)
Step 5
Close R studio
Step 6
Navigate to the subfolder ‘cold_folder’
Step 7
Open a R script using R studio
(The package library should correspond to that listed below.
This will indicate R studio is accessing the saved package
dependencies.)
Step 8
Execute the R code, which will utilize the project package library.
After the package library has been loaded using the above
steps, it is not necessary to re-load the package library for each
script. R studio will continue to access the package dependencies
for each script you open within the R studio session. If you
subsequently close R-studio, and then open scripts from within
the unbundle directory, R studio should still access the
dependencies without requiring re-loading of the saved package
snapshot.
When building mypackage, everything seems to work:
library(devtools)
build(vignettes = T, manual = T)
* checking for file ‘/storage/Documents/client/validate/mypackage/DESCRIPTION’ ... OK
* preparing ‘mypackage’:
* checking DESCRIPTION meta-information ... OK
* installing the package to build vignettes
* creating vignettes ... OK
* checking for LF line-endings in source and make files
* checking for empty or unneeded directories
* building ‘mypackage_0.1.tar.gz’
[1] "/storage/Documents/client/validate/mypackage_0.1.tar.gz"
However I can't find neither the PDF manual nor the vignette.
Vignette: followed workflow as described here, using RStudio / devtools / markdown. However:
vignette("mypackage")
Warning message:
vignette ‘mypackage’ not found
For the PDF manual I have tried this, but no success.
So, my question is: where can I find the PDF manual and the vignette?
I can find my PACKAGE-manual.pdf, where throughout PACKAGE is my package name, by first going to
C:\Users\USERNAME\AppData\Local\Temp\
within the Windows folder directory. You may have to enable hidden folders and files to see this. Within this folder are many many temp folders and other such things. Sort by date, and scroll down to where the folders are. The most recent one is the one you probably want; the ones that prefix with a "Rtmp" are the ones created by R.
Within the (probably) most recent Rtemp[blah] should be a folder entitled PACKAGE.Rcheck. In that PACKAGE.Rcheck folder should be the manual pdf PACKAGE-manual.pdf, assuming it was successfully created.
The full path string on my computer (for this package-creation run) is
C:\Users\USERNAME\AppData\Local\Temp\RtmpG0713j\PACKAGE.Rcheck\PACKAGE-manual.pdf.
You might have to search through a couple of Rtmp[blah] folders before you get the right one.
Not sure quite where RStudio puts it, but in a bare bones check operation the pdf version of the manual should be in a folder called mypackage.Rcheck If you created a mypackage-package.R file then when the package is installed, ?mypackage should lead you to the html version of the manual. The vignette you can get by installing your package and doing vignette("mypackage").
I don't know for the manual, but if you build from rstudio using the 'build and reload' button (nearby the check buttonl, the vignettes, if properly built, should end up in 'yourpackage' subfolder of your r library folder, i think in inst/doc sub sub folder.
Also, for vignettes did you try building them using devtools::build_vignettes ? Usually works for me.
I'm trying to write a vignette for a package in R. I've been following a tutorial from Vanderbilt University as well as the offical documentation.
I made a .Rnw Sweave file and put it into a subdirectory inst/doc inside my package. Inside the same subdirectory inst/doc, I put a folder example containing some example text files. My package has a function myparser(path) that I want to demonstrate in the vignette; myparser(path) creates several data frames by reading in the text files inside the folder with absolute path name path.
Then I checked the package using R CMD CHECK, and got this error:
* checking running R code from vignettes ...
‘mypackage-vignette.Rnw’ using ‘UTF-8’ ... failed
ERROR
Errors in running code in vignettes:
when running code in ‘mypackage-vignette.Rnw’
...
> library(mypackage)
Loading required package: ggplot2
> myparser("/example/")
Warning in file(file, "rt") :
cannot open file '/example/': No such file or directory
When sourcing ‘mypackage-vignette.R’:
Error: cannot open the connection
Execution halted
I see my attempt to use a relative pathway to the folder didn't work (probably should have been obvious to me), but I'm still not sure how to fix this situation. I don't want to replace path with an absolute pathway to the folder on my computer, because then the vignette's code won't be reproducible on other people's computers.
How can I include the example files in the package so that the vignette's code is reproducible? Am I even approaching this problem in the right way?
(Sorry this question isn't itself more reproducible!)
You can use system.file('doc', 'example', package = 'mypackage') to refer to that directory, because R will install the package before building vignettes, as you can see when you run R CMD build mypackage.