r-lib / pkgdown

Generate static html documentation for an R package

pkgdown

pkgdown is designed to make it quick and easy to build a website for your package. You can see pkgdown in action at https://pkgdown.r-lib.org: this is the output of pkgdown applied to the latest version of pkgdown. Learn more in vignette("pkgdown") or ?build_site.

Installation

# Install released version from CRAN
install.packages("pkgdown")

# Install development version from GitHub
# install.packages("pak")
pak::pak("r-lib/pkgdown")

Usage

Get started with usethis:

# Run once to configure your package to use pkgdown
usethis::use_pkgdown()

Then use pkgdown to build your website:

pkgdown::build_site()

This generates a docs/ directory containing a website. Your README.md becomes the homepage, documentation in man/ generates a function reference, and vignettes will be rendered into articles/. Read vignette("pkgdown") for more details, and to learn how to deploy your site to GitHub pages.

pkgdown 2.0.0 and Bootstrap 5

pkgdown 2.0.0 includes an upgrade from Bootstrap 3 to Bootstrap 5, which is accompanied by a whole bunch of minor UI improvements. If you’ve heavily customised your site, there’s a small chance that this will break your site, so everyone needs to explicitly opt-in to the upgrade by adding the following to _pkgdown.yml:

template:
  bootstrap: 5

Then learn about the many new ways to customise your site in vignette("customise").

In the wild

At last count, pkgdown is used by over 11,000 packages. Here are a few examples created by contributors to pkgdown:

• bayesplot (source): plotting functions for posterior analysis, model checking, and MCMC diagnostics.

• valr (source): read and manipulate genome intervals and signals.

• mkin (source): calculation routines based on the FOCUS Kinetics Report

• NMF (source): a framework to perform non-negative matrix factorization (NMF).

Comparing the source and output of these sites is a great way to learn new pkgdown techniques.

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

pkgdown's Issues

Error: Input to str_c should be atomic vectors

When I created docs for ggplot2 0.9.0:

Can't find help topic tableGrob
Error: Input to str_c should be atomic vectors

highlight is no longer available

The 'highlight' package is now archived which causes problems with installation.

Add option to remove/ignore \dontrun when generating staticdocs pages?

Hi Hadley,

In almost all of our rOpenSci packages we make web API calls, and so our examples are almost all wrapped in \dontrun. If we generate staticdocs pages, the examples then do not run. Is it possible to add an option in staticdocs to ignore \dontrun so that examples are run?

I wrote a little function to do this manually, but I'm sure you can come up with a much better solution:

nodontrun <- function(x) {
dat <- readLines(x)
dat[grep("@examples", dat)] <- "#' @examples"
dat[grep("#' }", dat)] <- ""
write(dat, # change directory to one of interest
paste("~newdirectory/R/",
x, sep=''))
}

files <- dir("pkgdirectory/R")
l_ply(files, nodontrun) # which puts all .R files in a new directory

Then run roxygenize() (or document() ) on the .R files in that new directory

build_package fails on vignette step

Trying to rebuild the staticdocs for knitcitations, I hit the following error

Building vignettes
Error in build_vignettes(package) : 
  could not find function "buildVignettes"

session:

> sessionInfo()
R version 2.15.0 (2012-03-30)
Platform: x86_64-pc-linux-gnu (64-bit)

locale:
 [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
 [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
 [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
 [7] LC_PAPER=C                 LC_NAME=C                 
 [9] LC_ADDRESS=C               LC_TELEPHONE=C            
[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       

attached base packages:
[1] parallel  stats     graphics  grDevices utils     datasets  methods  
[8] base     

other attached packages:
[1] doRNG_1.2.6    foreach_1.4.0  XML_3.9-4      RCurl_1.91-1   bitops_1.0-4.1
[6] xtable_1.7-0   bibtex_0.3-0   knitr_0.5.4    staticdocs_0.1

loaded via a namespace (and not attached):
 [1] codetools_0.2-8     devtools_0.6        digest_0.5.2       
 [4] evaluate_0.4.2      formatR_0.4         grid_2.15.0        
 [7] highlight_0.3.1     httr_0.1            iterators_1.0.6    
[10] knitcitations_0.0-2 markdown_0.4        memoise_0.1        
[13] parser_0.0-14       plyr_1.7.1          Rcpp_0.9.10        
[16] rjson_0.2.8         stringr_0.6         testthat_0.6       
[19] tools_2.15.0        whisker_0.1        

Error: Input to str_c should be atomic vectors

I attempted to run static docs on the repo found here: https://github.com/trinker/qdap2

I get an error message if I us examples = TRUE but not if I set examples = FALSE. I'm not sure if this is on my end or an issue with staticdocs.

Related error message: #2

Here's the output:

>  build_package(package="C:/Users/trinker/GitHub/qdap2", 
+      base_path="C:/Users/trinker/Desktop/qdapHTML/", examples = TRUE)
Loading qdap
Loading required namespace: gplots
Generating abbreviations.html
Generating action.verbs.html
Generating adjacency_matrix.html
Can't find help topic termco
Can't find help topic termco.d
Can't find help topic termco.c
Generating adverb.html
Generating all_words.html
Can't find help topic term.match
Generating bag.o.words.html
Generating blank2NA.html
Can't find help topic rm_row
Generating bracketX.html
Generating BuckleySaltonSWL.html
Generating capitalizer.html
Can't find help topic word_list
Generating clean.html
Generating cm_code.blank.html
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_code.overlap
Can't find help topic cm_code.combine
Can't find help topic cm_code.exclude
Can't find help topic cm_code.transform
Can't find help topic cm_code.transform
Generating cm_code.combine.html
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_code.blank
Can't find help topic cm_code.exclude
Can't find help topic cm_code.overlap
Can't find help topic cm_code.transform
Generating cm_code.exclude.html
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_code.blank
Can't find help topic cm_code.combine
Can't find help topic cm_code.overlap
Can't find help topic cm_code.transform
Generating cm_code.overlap.html
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_code.combine
Can't find help topic cm_code.transform
Generating cm_code.transform.html
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_range2long
Can't find help topic cm_time2long
Can't find help topic cm_df2long
Can't find help topic cm_code.blank
Can't find help topic cm_code.combine
Can't find help topic cm_code.exclude
Can't find help topic cm_code.overlap
Generating cm_combine.dummy.html
Can't find help topic cm_long2dummy
Can't find help topic cm_long2dummy
Generating cm_df.fill.html
Generating cm_df.temp.html
Generating cm_df.transcript.html
Can't find help topic cm_df2long
Can't find help topic cm_df.temp
Can't find help topic cm_df2long
Generating cm_df2long.html
Can't find help topic cm_df.temp
Generating cm_distance.html
Generating cm_dummy2long.html
Can't find help topic cm_long2dummy
Can't find help topic cm_combine.dummy
Error: Input to str_c should be atomic vectors

support the Authors@R tag in Description?

Seems like staticdocs doesn't pick up the Authors from the Authors@R tag. Is it recommended practice to still have the older Authors notation in DESCRIPTION as well?

Also looks like staticdocs tries to do something with vignettes but I'm not sure what. It seems to be ignoring my vignette at the moment.

Just to be on the same page, package I'm working on is cboettig/knitcitations, the html here

usage for s3 methods needs to include comment giving class name

error on build

I have tried to run build_site on my package and get the error below (this on Mac or Windows from the working directory of my package). Any suggestions as to the cause?

 build_site(pkg = ".", launch = interactive())
Error in if (file.exists(default)) return(default) : 
  argument is of length zero

Thanks
David

Rename Rd class

The Rd S3 class is used by the tools package, we should perhaps use another name to avoid collisions, or construct/use the objects more carefully.

References

https://bugs.r-project.org/bugzilla/show_bug.cgi?id=16448
gagolews/stringi#172
19da385

Look in inst/templates for templates

So packages can optionally override the defaults.

Optional index file

Packages should be able to provide an optional index file which is an Rd file of the following format:

\section{Title}{
  Text


  \itemise{
  \item topic
  \item topic
}

But it would be better to label individual topics with one or more sections, and then just supply a file that maps from section shortcut to title and header text. Could possibly embed in \concept{}.

readme.md

If readme.md present, convert it to html and include in the index.

dir.exists function does not exist

Hello, I have been trying to build something with the recently updated package and it says that dir.exists function does not exist.

Option to skip demos?

This may exist and I just can't find it, but I would find it very useful to either be able to outright skip demos or preferably just list the raw content without actually running them.

This is particularly a problem for me because our various MPI packages have demos that are not meant to be run interactively. So after the first is run and calls MPI_FINALIZE via finalize(), the later demos can not be run:

Rendering demos
*** The MPI_Comm_set_errhandler() function was called after MPI_FINALIZE was invoked.
*** This is disallowed by the MPI standard.
*** Your MPI job will now abort.
[wootabega-laptop:29826] Local abort after MPI_FINALIZE completed successfully; not able to aggregate error messages, and not able to guarantee that all other processes were killed!

build_package crashes on external links like \link[package:topic]{other name}

Hi Hadley,

I just discovered this yet another great tool from you!
I tried it on a package but got this error:

Generating registry.html
Error in find.package(package, lib.loc, verbose = verbose) : 
  there is no package called ‘registry:regobj’

It seems it breaks on the link \code{\link[registry:regobj]{registry}} which is supposed to link to the topic regobj of the package registry.
I will fork and try to provide a patch for this.

Thanks

Text of value section rendered as paragraphs rather than describe/dl

According to "Writing R Extensions"

\value{...}
Description of the function's return value.

If a list with multiple values is returned, you can use entries of the form

         \item{comp_i}{Description of comp_i.}

for each component of the list returned. Optional text may precede56 this list (see for example the help for rle). Note that \value is implicitly a \describe environment, so that environment should not be used for listing components, just individual \item{}{} entries.

However, they are not being rendered that way. An example is in ggplot2::stat_summary. The relevant section of the roxygen source:

#' @return a data.frame with additional columns:
#' \item{fun.data}{Complete summary function. Should take data frame as
#' input and return data frame as output}
#' \item{fun.ymin}{ymin summary function (should take numeric vector and
#' return single number)}
#' \item{fun.y}{y summary function (should take numeric vector and return
#' single number)}
#' \item{fun.ymax}{ymax summary function (should take numeric vector and
#' return single number)}

The corresponding .Rd file:

\value{
  a data.frame with additional columns:
  \item{fun.data}{Complete summary function. Should take
  data frame as input and return data frame as output}
  \item{fun.ymin}{ymin summary function (should take
  numeric vector and return single number)} \item{fun.y}{y
  summary function (should take numeric vector and return
  single number)} \item{fun.ymax}{ymax summary function
  (should take numeric vector and return single number)}
}

The corresponding HTML (from http://docs.ggplot2.org/0.9.3/stat_summary.html)

    <div class="Value">
      <h2>Value</h2>

      <p>a data.frame with additional columns:
  fun.dataComplete summary function. Should take
  data frame as input and return data frame as output
  fun.yminymin summary function (should take
  numeric vector and return single number) fun.yy
  summary function (should take numeric vector and return
  single number) fun.ymaxymax summary function
  (should take numeric vector and return single number)</p>

    </div>

This is in contrast with the \arguments section which is similarly formatted in the .Rd file, but rendered in a <dl>.

Newer version of markdown cause index page not to build

If I use markdown 0.6.4 then I can build the page fine. If I use the latest version I get an error that says:

Error in file(file, encoding = encoding) : invalid 'description' argument

This was for this repo: https://github.com/trinker/qdapTools

I haven't tested on other repos to actually find the root of the problem. For now I'm using an older version of markdown.

Incorrect output with attr id

For example, http://had.co.nz/ggplot2/docs/aes.html

aes(x = mpg, y = wt)

List of 2
 $ x: symbol mpg
 $ y:length 1 wt
  ..- attr(*, "id")= int 27

but this should be

List of 2
 $ x: symbol mpg
 $ y: symbol wt

Links to documentation of contributed packages on inside-r.org wrong

Documentation feedback [#937] for ggplot2 points out that the link for mapproject in the mapproj package points, incorrectly, to http://www.inside-r.org/r-doc/mapproj/mapproject. It should point to http://www.inside-r.org/packages/cran/mapproj/docs/mapproject. The difference appears to be whether the package is base (or is it recommended?) versus contributed.

Every function page opened.

For me (windows 7 R 3.1.0) when I build a site every individual function page is opened in the browser even if I set launch = FALSE.

Override default knitr template

Set option "markdown.HTML.template", default template at https://github.com/rstudio/markdown/blob/master/inst/resources/markdown.html

Error in building demos if 00Index has a stray empty line

Before running https://github.com/hadley/staticdocs/blob/master/R/build.r#L159, you need to filter out which(pieces[, 1] == "").

staticdocs no longer loading the package before calling the examples

It seems I now have to explicitly call library(mypackage) in each example in the documentation or I get "function not found". Surely this is not the intended behaviour?

• (Also not quite sure how demo works, but seems it wants files ending only in lowercase .r and doesn't recognize .R extensions)
• (Sorry If I'm bothering you on things you are already working on, I realize this is in somewhat early development).

Unknown tag: source

For \docType{data} Rd files parsed with staticdocs (0.1 installed from github), the following error for the \source{} tag is produced:

Generating Zooplankton.html
Unknown tag: source

The full Rd is pasted below (from the abd package).

\docType{data}
\name{Zooplankton}
\alias{Zooplankton}
\title{Zooplankton Depredation}
\format{A data frame with 15 observations on the following 3 variables.
\describe{ \item{treatment}{a factor with levels \code{control},
\code{high}, and \code{low}} \item{zooplankton}{a numeric vector}
\item{block}{a numeric vector} }}
\source{
  \emph{inferred from} Svanbäck, R. and D.I. Bolnick. 2007.
  Intraspecific competition drives increased resource use
  diversity within a natural population. \emph{Proceedings
  of the Royal Society of London Series B, Biological
  Sciences} 274: 839-844.
}
\description{
  Diversity of zooplankton (\code{zooplankton}) prey in
  each of 5 replicate blocks (\code{block}) of three
  treatment levels (\code{treatment}). By default,
  \code{block} is not coded as a factor.
}
\examples{
data(Zooplankton)
Zooplankton

Zooplankton$block <- factor(Zooplankton$block)
str(Zooplankton)

aov.fit <- aov(zooplankton ~ block + treatment,
  data = Zooplankton)
summary(aov.fit)
}
\keyword{datasets}

Line breaks lost if no executable code

e.g. ggplot2::translate_qplot_ggplot

R/settings.r: load_settings() fails if package has not staticdocs directory

The function pkg_sd_path returns character(0) and therefore load_settings() fails. A possible cure that works for me:

load_settings <- function(package) {
path <- file.path(pkg_sd_path(package), "index.r")
-- if (!file.exists(path)) return(list())
++ if (length(path)==0) return(list())

source(path)$value
}

Option to run (and remove) \dontrun examples

I tried the updated version of static docs, works well.

In the new version build_site lost the argument of rather or not to run the examples. That was nice. It may be nice to reinclude this.

Also it would be nice to have the ability to run examples that have been blotted from the CRAN check via \dontrun{} If one could choose to run this documentation for a static website even though it's "editted" out of the CRAN check, that would be nice.

staticdocs tried to build help files for emacs backup files like "xxx.Rd~"

When I used staticdocs to build help files from a source package, the source contained emacs backup files like "xxx.Rd~". These should be skipped during the build process.

HTML Characters in documentation

In using static docs it has the consequence of rendering examples that use html as html but this is true of the documentation as well. So using   in the documentation results in a blank space rather than the tag. This could be escaped but would appear in the latex document also which would look silly.

redirect output `base_path` to `gh-pages` branch?

It would be great to simply run staticdocs in, say, "gh-pages" mode such that the output immediately ends up on the gh-pages branch of the repository.

More generally, perhaps I'm stuck more with a git problem than anything to do with staticdocs -- I haven't found a reliable way to run staticdocs on my master branch (say, sticking the output into `base_path="inst/doc/html"), and then switch to gh-pages branch and pull in just the html. I tried this solution suggested on SO for a while, but found the commands a bit opaque and cannot troubleshoot when I get a gh-pages build error since I cannot even see actual files in the branch. Do you have any suggestions on how to do this better? (Whether or not this is something that could be automated in staticdocs). Much appreciated!

option for custom css

for now, we can only customize the templates, it would be great to customize the css, or even better, add theme support.

Failure to install staticdocs on R 3.0.0

highlight was released recently for CRAN again (out of archived) so I tried to install and then install staticdocs but get an error message I can't parse.

library(devtools)
install_github("staticdocs", "hadley")
.
.
.
Warning: S3 method 'plot.parser' was declared in NAMESPACE but not found
Error in library.dynam(lib, package, package.lib) : 
  DLL 'parser' not found: maybe not installed for this architecture?
ERROR: lazy loading failed for package 'staticdocs'
* removing 'C:/R/R-3.0.0/library/staticdocs'
Error: Command failed (1)

It seems that parser is installed though:

#Using pacman
> p_ver(highlight)
$Version
[1] "0.4.1"

> p_ver(parser)
$Version
[1] "0.1"

highlight no longer uses parser but staticdocs does.

Note this did lead me to a funny similar error written by Yihui.

List non-exported functions separately?

The latest iteration of staticdocs look great, love that it pulls in my readme.md file.

I write Roxygen documentation for internal functions as well as those I export for the user, but it's rather confusing to see them all listed together in the output documentation (perhaps that's the standard R manual behavior -- shows I don't browse the pdf manuals much). It would be great if these could be listed as "internal" or not shown?

Also minor issue: seems like staticdocs is missing an import/dependency on the markdown package at the moment.

staticdocs requires parser

I tried to install staticdocs in 3.0.0, but it requires parser from halpo, which gives an error

gram.y:248:28: fatal error: R_ext/rlocale.h: No such file or directory

under Windows 7.

build_site only works when there is an inst/staticdocs directory

This is not documented and I wonder if it is necessary. After the build, the directory is empty.

me@computer:~/git/R_package$ LANG=C Rscript -e 'library(staticdocs); build_site()'
Error in if (file.exists(default)) return(default) : 
  argument is of length zero
Calls: build_site -> as.sd_package -> load_index -> file.path.ci
Execution halted

Side note: the R object default should be tested for its length before file.exists(default) is called.

{{title}} in rendered index page is sometimes blank

For example, when building the boot package, the index page doesn't display the correct function title:

Help topics
* abc.ci
    - 
* acme
    - 
* aids
    - 
* aircondit(aircondit7)
    - Failures of Air-conditioning Equipment

The desired rendering should be:

Help topics
* abc.ci
    - Nonparametric ABC Confidence Intervals
* acme
    - Monthly Excess Returns
* aids
    - Delay in AIDS Reporting in England and Wales
* aircondit(aircondit7)
    - Failures of Air-conditioning Equipment

This happens because of some poor formatting in the .Rd files of the boot package. Specifically, the titles of these functions start with \n. This exception isn't handled correctly.

I have a fix and will submit with a pull request.

Run in non-interactive mode

Probably through devtools::R

to_html on plyr::aaply fail

Figure out why:

to_html(parse_rd("aaply", "plyr"), package = "plyr")

inherits argument in sd_icon() only follows one level

In the ggplot2 docs, the icon for stat_density2d inherits from geom_density2d, which in turn inherits from geom_contour. The code for icon_path only follows one level of inheritance, and so the generated page points to the nonexistent file geom_density2d.png:
http://docs.ggplot2.org/0.9.3.1/

Edit: I manually edited the ggplot2 docs webpage so that the icon for stat_density2d looks right, but that obviously didn't affect the underlying issue.

Generating the docs produces warning

Generating the docs produces a warning, that the index.html was not found. (I downloaded the source at 3 Jun) also the index.html looks a bit different that in used to. is it a feature? I was getting documentation like this
http://pinda.sifruje.cz/htmldocs_orig/index.html
now, I get this
http://pinda.sifruje.cz/htmldocs/index.html

Would you probably consider parsing equations by MathJax, again, the examples are
http://pinda.sifruje.cz/htmldocs_orig/rv_naive.html
after implementation
http://pinda.sifruje.cz/htmldocs/rv_naive.html

the license is very unrestrictive and one can probably add it as an option for compilation. If you wanted, I can share the modifications, but they are really basic so there is probably no need to...

Best,
T.

How to run to include plots

If I do

Rscript -e 'staticdocs::build_site()`

then they are not included. Do I need to run it interactively? Just because I am planning to run it on Travis, by https://github.com/metacran/r-builder.

integration / wrapper for knitr's knit_rd() function

Looks like knitr supports generating html files from the documentation using a new knit_rd function. (knitr/NEWS)

Install error on current version

looks like a typo? (On hadley@aa5e644c7ff2e00601fcdde76aafcd7b28c88770)

Installing with install_github or the old clone and R CMD INSTALL, I get the error:

* installing to library '/home/cboettig/R/x86_64-pc-linux-gnu-library/2.15'
* installing *source* package 'staticdocs' ...
** R
Error in parse(outFile) : 29:3: unexpected '}'
28:     browseURL(normalizePath(file.path(base_path, "index.html"))
29:   }
     ^

Use mathjax

<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

Problem with build_site()

Not sure if this is a documentation or code issue.

I have just installed staticdocs. First port of call is ?staticdocs which leads me to build_site().

However this returns the error:

Error in if (file.exists(default)) return(default) : 
  argument is of length zero

Here's what's happening:

• pkg_sd_path() is returning NULL as the staticdocs/ subdirectory hasn't been created
• therefore, in the call to load_index() we have file.path.ci(NULL, "index.R")
• which is a problem as this evaluates to character(0)

Creating the staticdocs/ directory (where pkg_sd_path() expects it to be) solves this problem.

"Don't run" examples do not render properly

When a don't run example is present, staticdocs will render it on the browser as follows:

## <strong>Not run</strong>: process_folder()

The problem is that the example line is added the <strong> tags in to_html.dontrun but it ultimately ends up in replay_html.source, where the < and > symbols are escaped (by escape_html). In the end <strong> is coded as <strong>

I'm going to propose a pull request that restores the correct symbols, but it's definitely a temporary patch to this problem.

On index, only display non-internal topics.

Check to see how library(help = package) does it.

Multiple return items

e.g. from ggplot2::stat_bin():

#' @return New data frame with additional columns:
#'   \item{count}{number of points in bin}
#'   \item{density}{density of points in bin, scaled to integrate to 1}
#'   \item{ncount}{count, scaled to maximum of 1}
#'   \item{ndensity}{density, scaled to maximum of 1}

Update documentation to match code

For example, as.sd_package() argument names in documentation do not match code:

• package / pkg
• base_path / site_path

Render demos