Skip to content

[Bioc-devel] not including vignette in R CMD check

6 messages · Martin Morgan, Kasper Daniel Hansen

Original
Kasper Daniel Hansen
# 
I have a package (to be submitted) with two "vignettes".

One is a user guide with quick examples, and should be checked as part
of R CMD check.

The other contains a runable longer analysis and I would like to
exclude it from the daily R CMD build due to length and resource
demands.  But it is in principle still runable on a bigger system.  I
want to include the Rnw file and I want the pdf to be indexed.

What is the preferred way for doing this, these days?  I know Wolfgang
has an old solution in tilingArray, but I was wondering if there is a
better way now.

Kasper
Martin Morgan
#
On 06/20/2012 12:46 PM, Kasper Daniel Hansen wrote:
Hi Kapser -- two suggestions

The first is a variant of Wolfgang's approach -- include the Rnw files 
for big and small, and the pdf file for big in vignettes/. Both Rnw 
files have \VignetteIndexEntry.

$ tree vig
vig
??? DESCRIPTION
??? NAMESPACE
??? vignettes
     ??? big.pdf
     ??? big.Rnw
     ??? Makefile
     ??? small.Rnw

Write a Makefile that compiles only small

$ cat vig/vignettes/Makefile
all: small.pdf

%.tex: %.Rnw
	"$(R_HOME)/bin/R" CMD Sweave $^

%.pdf: %.tex
	texi2dvi --pdf --clean $^

clean:
	rm -f *tex

(evaluate from the command line, e.g., for testing, with R CMD make). 
Build the package with R CMD build vig, and inspect the result

$ tar tzf vig_1.0.tar.gz
vig/
vig/inst/
vig/inst/doc/
vig/inst/doc/small.Rnw
vig/inst/doc/big.pdf
vig/inst/doc/small.pdf
vig/inst/doc/big.Rnw
vig/vignettes/
vig/vignettes/Makefile
vig/vignettes/small.Rnw
vig/vignettes/big.Rnw
vig/NAMESPACE
vig/DESCRIPTION

big and small are both indexed, e.g., by vignette(package="vig") or 
browseVignettes() or on package html help page; the .R source is 
available for both big and small.

A second approach is to manually create an inst/doc/index.html, which is 
then available on the package html help page (though vignettes aren't 
discoverable through other means, like vignette() / browseVignette()).

Martin

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Kasper Daniel Hansen
    

    

      
      #
    

  


  

      
Some comments

1) with my testing it appears that both Sweave files (big.Rnw and
small.Rnw) are run, but I could be wrong.
2) the clean target clearly is against the recommendations in R-exts

Unfortunately, the paragraph in R-exts on all of this is rather opaque
and seems weird.  For example "Whenever a Makefile is found, then R
CMD build will try to run make after the Sweave runs. The first target
in the Makefile should take care of both creation of PDF files and
cleaning up afterwards (including after Sweave), i.e., delete all
files that shall not appear in the final package archive." implies
that even the presence of a Makefile cannot prevent Sweave from
processing source files.

Anyway, reading the section carefully reveals "By default R CMD build
will run Sweave on all files in Sweave format in vignettes, or if that
does not exist, inst/doc (but not in sub-directories)."  This implies
that if both /vignettes and /inst/doc exists, Sweave is only run on
the files in /vignettes.

So my solution is simply to place small.Rnw in /vignettes and big.Rnw
and big.pdf in /inst/doc.

On my Mac it seems to work in the sense that vignettes() lists both of
them and if I use
  > help.start()
and go to
  packages -> PACKAGE_NAME->  overview of user guides and vignettes
I see both of them

(as an aside, it has been a long time since I used help.start but I
see that there is a "User Manuals" on the front page that lists all
the vignettes of the Recommended/Base packages, but not any other
package I have installed ... seems weird to me ...???)

Thanks,
Kasper

        
On Thu, Jun 21, 2012 at 10:08 AM, Martin Morgan <mtmorgan at fhcrc.org> wrote:

            

      
      
      
    

        

      
      
    

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Martin Morgan
    

    

      
      #
    

  


  

      
On 06/21/2012 08:42 PM, Kasper Daniel Hansen wrote:

            

      
      
      
    

        
OK, sorry for my misleading advice and thanks for clearing this up. Martin

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Kasper Daniel Hansen
    

    

      
      #
    

  


  

      
On Fri, Jun 22, 2012 at 12:07 AM, Martin Morgan <mtmorgan at fhcrc.org> wrote:

            

      
      
      
    

        
Well, I was also convinced the Makefile would work.  Very weird that
Sweave gets run even if the Makefile is present, and hard to detect.
I only found out because I wanted to move the "rm -f" line up to be
part of the %.pdf target and suddenly I started seeing both big.tex
and small.tex.

Also weird that when you inspect the source build tarball, it contains
the vignette directory and also a copy of the source files in
inst/doc, so it has both vignettes/small.Rnw and inst/doc/small.Rnw.
Apparently the vignettes dir does not really get installed, but is
still present.  As an aside, the tangled R code (small.R) is generated
at install time.

Anyway, I have my solution,
Kasper

            

      
      
      
    

        

      
      
    

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Kasper Daniel Hansen
    

    

      
      #
    

  


  

      
There has been some off-list discussion about the philosophy of
inst/doc and vignettes.  I don't really know what the real intention
is, but after experimenting and looking at the content of the source
dir, the source tarball and the install dir (and also reading the
documentation), this is my current understanding:

/inst/doc is for the documents, but not necessarily the document
sources.  Essentially, think of the directory as what needs to get
installed (but not build).  A bit like the difference between src
(where the source is) and libs (where the libraries gets installed).

If I in my source tree have
  vignettes/test.Rnw
the following will be present in the source tarball
  vignettes/test.Rnw
  inst/doc/test.pdf
  inst/doc/test.Rnw
Note that the pdf gets moved to inst/doc.  The reason why the test.Rnw
gets copied to inst/doc is - I think - because it is supposed to be
installed.  I don't really understand why the /vignettes directory is
still present to be honest.
Now, for installation we only get
  package_maindir/doc/test.pdf
  package_maindir/doc/test.Rnw
  package_maindir/doc/test.R
"only" in the sense that the vignettes dir is gone.

The reason the Rnw files gets copied over from vignettes to inst/doc
is that the Rnw actually needs to get installed.  Also, note the
test.R file gets created at install time.

Kasper

On Fri, Jun 22, 2012 at 12:21 AM, Kasper Daniel Hansen

        
<kasperdanielhansen at gmail.com> wrote: