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

Kasper Daniel Hansen kasperdanielhansen at gmail.com
Fri Jun 22 16:32:51 CEST 2012 

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:
> On Fri, Jun 22, 2012 at 12:07 AM, Martin Morgan <mtmorgan at fhcrc.org> wrote:
>> On 06/21/2012 08:42 PM, Kasper Daniel Hansen wrote:
>>>
>>> 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.
>>
>>
>> OK, sorry for my misleading advice and thanks for clearing this up. Martin
>
> 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
>
>>> 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:
>>>>
>>>> On 06/20/2012 12:46 PM, Kasper Daniel Hansen wrote:
>>>>>
>>>>>
>>>>> 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.
>>>>
>>>>
>>>>
>>>> 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
>>>>>
>>>>> _______________________________________________
>>>>> Bioc-devel at r-project.org mailing list
>>>>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Computational Biology / Fred Hutchinson Cancer Research Center
>>>> 1100 Fairview Ave. N.
>>>> PO Box 19024 Seattle, WA 98109
>>>>
>>>> Location: Arnold Building M1 B861
>>>> Phone: (206) 667-2793
>>
>>
>>
>> --
>> Computational Biology / Fred Hutchinson Cancer Research Center
>> 1100 Fairview Ave. N.
>> PO Box 19024 Seattle, WA 98109
>>
>> Location: Arnold Building M1 B861
>> Phone: (206) 667-2793

More information about the Bioc-devel mailing list