Figures (R code execution results) in HTML help pages for a R package

Question

When writing a package in R, you can create the help pages in Rd format and then convert them into HTML pages. If the help page includes the example code, it is printed in Section "Examples".

For example, there are two pages for the function "prcomp" of the package "stats":

1. Only example code: http://stat.ethz.ch/R-manual/R-patched/library/stats/html/prcomp.html
2. Example Code + Results with Figures: http://rgm2.lab.nig.ac.jp/RGM2/R_man-2.9.0/library/stats/man/prcomp.html

The question is how to generate the results of R code execution, and particularly include the output figures? That corresponds to Section "Results".

I use the following command to convert Rd to HTML:

R CMD Rdconv -t html $rdfile > $rdname.html

That calls the R function http://stat.ethz.ch/R-manual/R-devel/library/tools/html/Rd2HTML.html.

I will appreciate any comments or suggestions. Thanks.

Answer 1

You might want to check out the helpr package which provides a web front end to the documentation that, as well as many other improvements, displays the results of examples in line.

Answer 2

Thanks @rcs and @hadley for your comments.

Actually , both proposed solutions don't seem to fit to my needs. Embedding images in Rd format is not the case, as I use transition Roxygen>Rd. The package 'helpr' is really impressive, but I think it suits more for building a knowledge base of all packages you have installed in your computer. I needed something more basic with flexibility to do changes by myself as a package developer.

Finally, I got what I expected, fitSpline.html. That is quite similar to the reference page I put in the question, prcomp.html.

I found that there is no way to adopt the package 'tools' to have images in HTML documentation, at least for now. Thus, I wrote a bash script that takes a Rd file on the input, extracts the section '\examples' and get html/image output by running Sweave. Afterwards, the html part of the 'Results' section is merged with the html page obtained by the command 'R CMD Rdconv -t html'.

That seems to be a lot of code, but I just want to share my solution with those who also writes R packages.

Best regards, Andrey

#!/bin/bash

rdfile="fitSpline.Rd"
rdname=$(echo "$rdfile" | cut -d'.' -f1)

rfile=$rdname.R
sed -n '/\examples{/,/}/p' $rdfile > $rfile # text between two patterns
sed -i 's/\\examples{//' $rfile # remove pattern '\examples{'
sed -i 's/}$//' $rfile # remove the character '}'

rnwfile=$rdname.Rnw
cp $rfile $rnwfile
sed -i '1 i png("Rplot%03d.png")' $rnwfile
sed -i '1 i  <<example, echo=true, results=tex>>=' $rnwfile
sed -i '$ a dev.off()' $rnwfile
sed -i '$ a @' $rnwfile

texfile=$rdname.tex
R CMD Sweave $rnwfile
sed -i 's/\\begin{Schunk}//' $texfile
sed -i 's/\\begin{Sinput}//' $texfile
sed -i 's/\\end{Schunk}//' $texfile
sed -i 's/\\end{Sinput}//' $texfile
sed -i '/^$/d' $texfile # remove empty lines

reshtmlfile=$rdname.results.html
echo "<h3>Results</h3>" > $reshtmlfile
echo "<pre>" >> $reshtmlfile
cat $texfile >> $reshtmlfile
echo "</pre>" >> $reshtmlfile

for fig in $(ls *.png) ; do
  echo "<br><a href=\"$fig\"><img src=\"$fig\"></a>" >> $reshtmlfile
done

htmlfile=$rdname.html
R CMD Rdconv -t html $rdfile > $htmlfile

sed -i 's/<\/body>//' $htmlfile
sed -i 's/<\/html>//' $htmlfile
cat $reshtmlfile >> $htmlfile
echo "</body>" >> $htmlfile
echo "</html>" >> $htmlfile

Answer 3

I thought of letting you know that there is a new solution coming out in R 2.14 (see here):

Rd markup has a new \figure tag so that figures can be included in help pages when converted to HTML or LaTeX. There are examples on the help pages for par() and points().

Hadley, your helpr library sounds great, I would love to try it out once you put a newer version of it on CRAN.