Skip to content

[Bioc-devel] RMarkdown for vignettes

7 messages · James W. MacDonald, Henrik Bengtsson, Andrzej Oleś +2 more

Original
Gordon Ball
# 
Hello

Is it possible to use (RStudio's) rmarkdown package as a vignette
builder for the upcoming release?

ie, with the (at least locally working) configuration

DESCRIPTION

    Suggests: knitr, rmarkdown, BiocStyle
    VignetteBuilder: knitr

vignette/vignette.Rmd

    ---
    title: ...
    output: BiocStyle::html_document
    vignette: >
        %% \VignetteEngine{knitr::rmarkdown}
        %% \VignetteIndexEntry{...}
    ----

I couldn't find any explicit reference to markdown vs rmarkdown in the
package guidelines. The documentation for [BiocStyle] indicates that it
isn't possible to build package vignettes with the newer rmarkdown - is
that still correct?

I note that the newer [rmarkdown] is now in CRAN, so presumably can be
used by the builders - but do they have the non-R dependency (pandoc)
available?

The rationale for wanting rmarkdown instead markdown is support for a
few extended features, particularly being able to cite from a bibtex
file (which as far as I know isn't possible with the older markdown).

Thanks

Gordon Ball
Computational Medicine Group
Karolinska Institute



[BiocStyle]:
http://www.bioconductor.org/packages/devel/bioc/vignettes/BiocStyle/inst/doc/HtmlStyle.html

[rmarkdown]: http://cran.r-project.org/web/packages/rmarkdown/
James W. MacDonald
# 
Hi Gordon,

Sean Davis has something about this on his blog:

http://watson.nci.nih.gov/~sdavis/blog/convert_from_sweave_to_r_markdown_vignettes/

Best,

Jim
On Fri, Oct 3, 2014 at 9:06 AM, Gordon Ball <gordon.ball at ki.se> wrote:

            

      
      
      
    

        

      
      
    

        

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Henrik Bengtsson
    

    

      
      #
    

  


  

      
I think it requires Bioc core to make a statement that pandoc will be added
to the list of external software that can be assume to exist on the servers.

If it is also expected that users should be able to rebuild all
vignettes/documents themselves, then that assumption has to be extended to
the users as well. BTW, is there such an assumption on LaTeX-dependent
packages today?

Installing pandoc is not that hard and lightweight (much smaller than
LaTeX), but it does add one more installation. On the other hand, it opens
up for doing lots of other neat things.

Henrik

        
On Oct 3, 2014 6:40 AM, "James W. MacDonald" <jmacdon at uw.edu> wrote:

        

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

        

  
  


  


      

    

    

      
      

        


  

        

      Dan Tenenbaum
    

    

      
      #
    

  


  

      
----- Original Message -----

            

      
      
      
    

        
Pandoc is installed on the build servers. Several packages use it.

            

      
      
      
    

        
Users only need LaTeX (or pandoc) if they are going to build package vignettes from svn. Source packages (as well as binary packages of course) already contain built vignettes.

Dan

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Andrzej Oleś
    

    

      
      #
    

  


  

      
Hi Gordon, James,

thank you for pointing this out! At the time BiocStyle for markdown
documents was developed 'rmarkdown' was not yet on CRAN and couldn't
be used as a vignette builder engine.
As things changed in the meantime, the approach described by Gordon
should be just fine. I will update the BiocStyle vignette accordingly.

Best,
Andrzej

        
On Fri, Oct 3, 2014 at 4:51 PM, Dan Tenenbaum <dtenenba at fhcrc.org> wrote:

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    
3 days later

    

      
      

        


  

        

      Gordon Ball
    

    

      
      #
    

  


  

      
Sorry to re-open this thread, but it appears that this configuration
works with some builders but not others. There appear to be two
different failure modes:

Works with: oaxaca, perceval (OSX 10.6, 10.9)

Fails with: moscato1 (windows 2008)

    InvalidUrlException
"D:%5Cpackagebuilder%5Cjobs%5CSTATegRa_20141007024617%5CR-libs%5CBiocStyle%5Cresources%5Chtml%5Cbioconductor.css"
"Invalid scheme"

This appears to be an error in specific pandoc versions where it
interprets a windows drive letter as a URL scheme - see
https://github.com/jgm/pandoc/issues/1558

Fails with: zin1 (linux ubuntu 12.04)

    pandoc: Error running filter pandoc-citeproc
    pandoc-citeproc not found in path

The filter for processing references doesn't seem to be available. In
14.04 this is the package `pandoc-citeproc`, but it doesn't appear to be
available for 12.04. I assume this is only an issue if the Rmd document
includes a `bibliography:` field in the header.



Are these issues likely to be addressable for this release? If not, can
we get away with shipping a static vignette to avoid these problems?

(The build log in question is
http://bioconductor.org/spb_reports/STATegRa_0.99.3_buildreport_20141007025338.html
)

Thanks

Gordon Ball

        
On 04/10/14 00:02, Andrzej Ole? wrote:

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Dan Tenenbaum
    

    

      
      #
    

  


  

      
This is fixed now.

http://bioconductor.org/spb_reports/STATegRa_0.99.4_buildreport_20141007100210.html

Dan


----- Original Message -----