Post-process pkgdown version of Biocstyle vignette

fix_biocstyle_articles.R

#' Post-process pkgdown Version of Biocstyle Vignette
#'
#' Takes HTML vignette rendered by [pkgdown::build_articles()] from R markdown
#' using [BiocStyle::html_document2()] and post-processes it to fix
#' features not supported by [rmarkdown::render()] (used by `build_articles`
#' under the hood).
#'
#' In order to match the table and figure references to the correct table or
#' figure, the function requires both the HTML rendered by
#' [pkgdown::build_articles()] and the version rendered by
#' [devtools::build_vignettes()] (or an equivalent vignette rendered with
#' [BiocStyle::html_document2()]).
#'
#' The following issues are fixed:
#'  - References to tables and figures (original marked up using `\@ref()`) are
#'  converted to HTML hyperlinks and corresponding anchors are put in the table
#'  and figure captions.
#'  - Prefixes (e.g. "Table 1:" or "Figure 1:") are added to table and figure
#'  captions.
#'  - The anchors are styled with an offset to allow for the navbar
#'  - The figure captions are styled as the table captions to differentiate from
#'  the body text.
#'  - The abstract is styled so that it stands out from the body text.
#'
#'  The HTML file(s) created by [pkgdown::build_articles()] are over-written
#'  with the new version(s). The only material differences between the
#'  post-processed R markdown style vignette and the Biocstyle vignette
#'  is that post-processed version does not have the date the file was generated
#'  or the package version number.
#'
#' @param pkg Path to the source package.
#' @param output Path to the HTML vignette rendered by
#' [pkgdown::build_articles()].
#' @param input Path to the HTML vignette rendered with
#' [BiocStyle::html_document2()], by default `inst/doc` as used by
#' [devtools::build_vignettes()].
#'
#' @references This is a hack to fix the incompatibility between
#' [BiocStyle::html_document2()] and [pkgdown::build_articles()], check if a
#' better solution is now available https://github.com/hadley/pkgdown/issues/323.
#'
#' @return Nothing is returned, the function is called for its side-effect of
#' modifying the HTML file(s) produced by [pkgdown::build_articles()].
#'
#' @examples
#' \dontrun{
#' # first build package vignette, e.g. as follows
#' library(devtools)
#' build_vignettes()
#'
#' # second create version for pkgdown site, e.g.
#' library(pkgdown)
#' build_articles() # or build_site()
#'
#' # post-process HTML vignettes created by pkgdown
#' fix_biocstyle_articles()
#'
#' # (optional) remove vignette files in inst/doc
#' clean_vignettes()
#' }
fix_biocstyle_articles <- function(pkg = ".", output = "docs/articles",
                                   input = "inst/doc") {
    require(pkgdown)
    pkg <- as_pkgdown(pkg)
    path <- rel_path(output, pkg$path)
    html <- pkg$vignettes$file_out
    for (h in html){

        # get information from biocstyle vignette

        original <- readLines(file.path(pkg$path, input, h))
        ## get Table reference labels
        id <- grep("^<span id=\"tab:", original)
        tab_label <- sub("^<span id=\"(tab:[^\"]+)\".*",
                          "\\1", original[id])
        ## get Figure reference labels
        id <- grep("^<div class=\"figure\"><span id=\"fig:", original)
        fig_label <- sub("^<div class=\"figure\"><span id=\"(fig:[^\"]+)\".*",
                          "\\1", original[id])

        # fix up pkgdown vignette

        output <- readLines(file.path(path, h))
        ## fix up Table references
        for (i in seq_along(tab_label)){
            output <- gsub(paste0("@ref(", tab_label[i], ")"),
                           paste0("<a href=\"#", tab_label[i], "\">",
                                  i, "</a>"),
                           x = output, fixed = TRUE)
        }
        ## fix up Figure references
        for (i in seq_along(fig_label)){
            output <- gsub(paste0("@ref(", fig_label[i], ")"),
                           paste0("<a href=\"#", fig_label[i], "\">",
                                  i, "</a>"),
                           x = output, fixed = TRUE)
        }
        ## insert Table prefixes
        tab_start <- grep("^<caption>", output) + 1
        output[tab_start] <- paste0("<span class=\"offset\" id=\"", tab_label,
                                    "\">Table ",
                                    seq_along(tab_label), ": </span>",
                                    output[tab_start])
        ## insert Figure anchors
        fig_start <- grep("<div class=\"figure\">", output, fixed = TRUE)
        output[fig_start] <- paste0(output[fig_start],
                                    "<span class=\"offset\" id=\"", fig_label,
                                    "\"></span>")
        ## insert Figure prefixes
        cap_start <- grep("<p class=\"caption\">", output, fixed = TRUE) + 1
        output[cap_start] <- paste0("Figure ", seq_along(fig_label), ": ",
                                    output[cap_start])
        ## add in custom css
        end_head <- grep("^</head>", output)
        part1 <- output[seq_len(end_head - 1)]
        part2 <- output[-seq_len(end_head - 1)]
        new <- c(part1,
                 "<style type=\"text/css\">",
                 ".offset {",
                 "  padding-top: 60px;",
                 "}",
                 ".caption {",
                 "  padding-top: 8px;",
                 "  padding-bottom: 8px;",
                 "  color: #777;",
                 "  text-align: left;",
                 "}",
                 "p.abstract{",
                 "  font-size: 24px;",
                 "  font-family: inherit;",
                 "  text-align: center;",
                 "  font-weight: bold;",
                 "}",
                 "div.abstract{",
                 "  margin: auto;",
                 "  width: 90%;",
                 "  padding-bottom: 15px;",
                 "}",
                 "div.contents{",
                 "  border-top: 1px solid #eee;",
                 "  padding-top: 9px;",
                 "}",
                 "</style>",
                 part2)
        writeLines(new, file.path(path, h))
    }
}