I've noticed that many books built using RBookdown will have an "on this page" section in the upper right hand corner (displays book subsections). You can see what I'm referring to by looking at Hadley Wickham's "R4DS" book here: https://r4ds.had.co.nz/data-visualisation.html.
After digging through the source code I can't figure out how to create this section. Does anyone know how this section is created?
They are using a new document format bookdown::bs4_book. This new format renders the section in question. See the rdrr.io man page for some more information.
To use the new format, first install the latest bookdown version from github with remotes::install_github("rstudio/bookdown"). Then you can specify the new format for your bookdown project in your _output.yaml file like they have done here.
Note, there are a number of dependencies required to use the new format including downlit, bslib, and notably a version of htmltools >= 0.5.0.9001. downlit can be installed with remotes::install_github("r-lib/downlit") while bslib can be installed with remotes::install_github("rstudio/bslib"), and one would normally be able to install htmltools with just remotes::install_github("rstudio/htmltools"). However, as of this writing the latest version of htmltools is failing its R-CMD-Check, and I was unable to install it on my system. Therefore, I installed the 0.5.0.9001 version by referencing the requisite commit with remotes::install_github("rstudio/htmltools#8c82cc4f869f75ac4f13ee78ab322790ec316d3f").
Related
I recently released a vignette with version 1.1 of my R package. The Rmd for the vignette can be found here. When I create the vignette locally, I see author information and the table of contents at the top of the vignette, as expected. However, when I submitted this package to CRAN and the vignette was created there, I no longer see the table of contents or author information. Does anyone know why this may be happening?
Thanks.
I glanced at your DESCRIPTION here and noticed that the VignetteBuilder field does not contain rmarkdown. Since you are using knitr::rmarkdown as an engine, I suspect that you need:
VignetteBuilder: knitr, rmarkdown
Here is a relevant paragraph from the R-exts manual:
The VignetteBuilder field names (in a comma-separated list) packages that provide an engine for building vignettes. These may include the current package, or ones listed in Depends, Suggests or Imports. The utils package is always implicitly appended. See Non-Sweave vignettes for details. Note that if, for example, a vignette has engine knitr::rmarkdown, then knitr provides the engine but both knitr and rmarkdown are needed for using it, so both these packages need to be in the VignetteBuilder field and at least suggested (as rmarkdown is only suggested by knitr, and hence not available automatically along with it). Many packages using knitr also need the package formatR which it suggests and so the user package needs to do so too and include this in VignetteBuilder.
This is not a guaranteed fix, but it is maybe a first step.
R package README.md files can have those nice CRAN version badges from Metacran (see e.g. https://github.com/hadley/devtools). I am wondering:
Can I also show the current development version (as per DESCRIPTION line "Version: ___")?
I can get started if line numbers are known:
https://stackoverflow.com/a/28332095/1587132
Rstudio renders it nicely as html if I use
<script src="http://gist-it.appspot.com/github/brry/berryFunctions/blob/master/DESCRIPTION?slice=3:5"></script>
However, it seems to be completely ignored in https://github.com/brry/berryFunctions#intro
I have a package on CRAN that I would like to add a ChangeLog for, but I cannot find information anywhere on how to do this.
I looked on the "Writing R Extensions" document that CRAN provides, but it only mentions ChangeLogs and gives no direction (I could find) about how to create one.
I noticed from downloading tarballs from other packages on CRAN (e.g. seacarb) that their ChangeLogs are Unix Executable Files (I'm on a Mac) so that's not too helpful.
I imagine this is a common problem, but Googling "changelog R package" just brings up ChangeLogs for really popular packages...
You can either provide a NEWS file or a ChangeLog file, or both, to describe changes in your package. You have to add these files in the top level folder of your project, i.e. in the same folder as your DESCRIPTION and NAMESPACE.
This is documented in the R package manual in paragraph 1.1 Package structure. In particular, this paragraph points to the GNU standard:
For the conventions for files NEWS and ChangeLog in the GNU project see http://www.gnu.org/prep/standards/standards.html#Documentation.
Hadley points out that "Generally you should use a NEWS file, and not ChangeLog. I think the purpose of ChangeLog (to list every change), has been subsumed by source code control".
To create a NEWS file, simply create a text file called NEWS in the top level folder of your package. You maintain this file by hand.
Here is an extract from the NEWS file from my package miniCRAN (CRAN link):
miniCRAN v0.0-21 (Release date: 2014-08-18)
==============
Changes:
* Changes to defaults in plot.pkgDepGraph() to move legend to left of plot area.
miniCRAN v0.0-20 (Release date: 2014-08-18)
==============
Changes:
* Modified examples to reduce running time, mostly using \dontrun{} sections
NEWS.md files are now also supported by CRAN (Which renders them as html) and more recently by the news() function.
https://cran.r-project.org/doc/manuals/r-devel/NEWS.html
If you are following this and opting for NEWS.md then make sure news() reads the same correctly (at the same time it looks great on GitHub).
You can do the same in your local builds of the packages.
It seems like it has a specific format you have to adhere with.
I tried like this (and it works) (check here)
# *News*
# tidycells 0.1.9 (2019-07-31)
## Initial Submission
* **CRAN** Initial Submission
# tidycells 0.1.5 (2019-07-30)
## Final Codebase Release in GitHub
* Final Release in GitHub for **CRAN** Submission
* Only Minor Documentation Change after this and before next **CRAN** Submission
# tidycells 0.1.0 (2019-07-25)
## Initial Release to GitHub
* Initial Release to GitHub
* Prior to this it was private package
I'm planning to condense some of my code into a package, and was looking at the source of a few published packages on CRAN as a guide. I notice many packages include the file R\zzz.R, so I presume there must be some convention surrounding this.
However, I cannot find any mention of zzz.R in the official Writing R Extensions guide. What is this file for, and do I need to include one in my package? Why is it named the way it is - why not zzzz.R?
It's a file where one usually puts actions on load of the package. It is tradition/convention that it's called zzz.R and could be called anything.R
You only need to include this if you want you package to do something out of the ordinary when it loads. Keep looking at what people put in there and you'll begin to get a sense of what they're used for.
This zzz.R file was also mentioned by Hadley Wickham in his book "R packages", at the bottom of "When you do need side-effects" section.
https://r-pkgs.org/Code.html#when-you-do-need-side-effects
If you use .onLoad(), consider using .onUnload() to clean up any side effects. By convention, .onLoad() and friends are usually saved in a file called R/zzz.R. (Note that .First.lib() and .Last.lib() are old versions of .onLoad() and .onUnload() and should no longer be used.)
Can I include some PDF in the pkg/doc folder so that the vignette function works, but no corresponding Rnw, Rtex, etc exists?
I am thinking of slides or documents containing markdown text weaved with R chunks, which have a different build process and hence different file extensions.
The writing R extensions guide suggests that it should be possible to include documents which can not be build at installation time, but the vignette function seems to look for files with special extensions (Rnw, Rtex, etc) and also for a file called vignette.rds.
Any hints are appreciated.
I asked about this several years ago, and while Fritz Leisch is amenable to the idea, he hasn't had the time to implement it.
(Cross-posted from a response I just left on R-help:)
As a workaround, you could include your own xvignette function in your package: see below.
It won't show you indices, but it will pick up any appropriately named file that you include in the inst/doc directory of your
package ...
xvignette <- function(vname,pkg,ext="pdf") {
vname <- paste(vname,ext,sep=".")
fn <- system.file("doc",vname,package=pkg)
if (nchar(fn)==0) stop("file not found")
utils:::print.vignette(list(pdf=fn))
invisible(fn)
}
You'll have to somehow alert your package users to the fact that this alternative documentation exists -- perhaps in the help file for the package itself.
You might fill in the default value of pkg above with your package name to make it easier on the user: I thought about using some variant of getPackageName(environment(xvignette)) to do it automatically, but that seems too complicated ...
Brian Ripley also mentioned in his response to the question that:
At present vignette() means Sweave documents, as only they have
metadata like titles. This is planned to be changed soon.
... but I don't know what "soon" means (it will be about 6 months until 2.14.0 comes out, I think)
edit: http://article.gmane.org/gmane.comp.lang.r.devel/28449 details another workaround (creating a dummy vignette that incorporates the existing PDF file)
edit 2: And
here's what Yihui Xie has to say about including knitr-based vignettes in packages (essentially another "dummy vignette" strategy)
vignette about non-Sweave vignettes from the R.rsp package
This is supported natively as of R 3.0.0, see http://yihui.name/knitr/demo/vignette/.
Instructions to use knitr as vignette engine boil down to:
add %\VignetteEngine{knitr::knitr} to the Rnw source document (note you still need %\VignetteIndexEntry{} as before)
specify VignetteBuilder: knitr in the package DESCRIPTION file
add Suggests: knitr in DESCRIPTION if knitr is needed only for vignettes
See also the official R documentation on that topic.