[Bioc-devel] Missing vignette on my BioConductor page

[Martin Morgan]

On 09/16/2016 10:02 AM, Marine Rohmer wrote:
> Dear Martin,
>
> Thank you again for your precious help!
>
> Now i've removed the VignetteEngine tag, I see "* creating vignettes ...
> OK" when doing R CMD build. And there is a pdf vignette in my ISoLDE/doc
> subdirectory of ISoLDE.Rcheck. Great, thank you!
>
> I understand the interest of including code chunks. However this makes
> my code examples look more complicated in the vignette, because I have
> to add a lot of "system.file()" code lines to get real input text file
> for all my examples. Whatsmore, with real code chunks, the "creating
> vignettes..." step is running so much time. For those reasons I will
> prefer not do to so. If those reasons are irrelevant feel free to tell
> me. Is there a safe way to add another document, a kind of user guide
> which will not be a vignette, as I saw for other packages?

Hello Marine,

You can have multiple 'vignettes', just name them foo.Rnw, bar.Rnw, ...

Most code chunks should be evaluated; if it takes more than the guidelines

   http://bioconductor.org/developers/package-guidelines/#correctness

suggest to build, then you need to tailor your example to be less 
demanding; for your own internal purposes, it is possible to build 
without vignettes -- R CMD build --no-build-vignettes MyPkg

It is possible, and acceptable, to have *some* code chunks that are not 
visible, or that are not evaluated, e.g.,

<<data-file, echo=FALSE>>=
fl = system.file(...)
@

To start the work flow, choose the directory in which...

<<data-file-theirs, eval=FALSE>>=
fl = file.choose()
@

I'm not sure that I have the syntax exactly right... Note that some 
users follow the printed vignette exactly, so if you hide too much they 
won't be able to replicated the work flow you are trying to illustrate.

Hope that helps,

Martin

>
> Regards,
>
> Marine R.
>
> Le 14/09/2016 à 14:59, Martin Morgan a écrit :
>> On 09/14/2016 08:49 AM, Marine Rohmer wrote:
>>> Hi Martin, thank you so much for you answer!
>>>
>>> I'm not sure to have well understood what is my problem, maybe I missed
>>> somewhere some basic learning about how to package.
>>>
>>> According to "The vignette" section from "Bioconductor: Package
>>> guidelines" and probably other guidelines I could have read, I've
>>> created a .Rnw document within a "vignettes" subdirectory. It compiles
>>> with pdflatex. No need for knitr. I have written some code examples but
>>> not included "evaluated code chunks" within my .Rnw file.
>>>
>>> What is the problem: knitr, the code chunks, or another thing?
>>
>> At the top of your file you've chosen to use knitr for compilation by
>> saying
>>
>> %\VignetteEngine{knitr::knitr}
>>
>> so you have to include in the DESCRIPTION
>>
>> Suggests: knitr
>> VignetteBuilder: knitr
>>
>> Or you could remove the VignetteEngine tag if you do not wish to use
>> knitr, and make no further changes.
>>
>> You can test that things are working by (a) removing the pdf version
>> of the vignette from the vignettes directory then (b) build the package
>>
>>   R CMD build ISoLDE
>>
>> you'll see
>>
>> * installing the package to build vignettes
>> * creating vignettes ... OK
>>
>> which you would not see without the changes above. You can then look
>> in the resulting tarball for an inst/doc directory that will now
>> contain the built vignette.
>>
>> Bioconductor vignettes are required to have evaluated code chunks
>> rather than 'copy-and-paste' commands. This keeps the vignette closer
>> to reality than a work of fiction, and provides some confidence that
>> the code is functioning at least approximately the way the author
>> intended. So one getting the vignette to compile, you should replace
>> the copy-paste code with real code
>>
>> <<my-chunk>>=
>> 1  + 1
>> @
>>
>> Hope that helps...
>>
>> Martin
>>
>>>
>>> You can find attached my vignettes subdirectory + the compiled vignette
>>> (pdf file).
>>>
>>> Thank you again for your help,
>>>
>>> Regards,
>>>
>>> Marine R.
>>>
>>>
>>>
>>> Le 13/09/2016 à 16:35, Martin Morgan a écrit :
>>>> Hi Marine -- mail sent to bioc-devel from non-subscribers is silently
>>>> dropped; I could not spot a subscription that might be yours, are you
>>>> subscribed?
>>>>
>>>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>>>>
>>>> I guess you mean the package ISoLDE. Here's the 'build' report for
>>>> release
>>>>
>>>> http://bioconductor.org/checkResults/release/bioc-LATEST/ISoLDE/zin2-buildsrc.html
>>>>
>>>>
>>>>
>>>> and devel
>>>>
>>>> http://bioconductor.org/checkResults/devel/bioc-LATEST/ISoLDE/zin1-buildsrc.html
>>>>
>>>>
>>>>
>>>> If the vignette were being built, it would indicate that in the
>>>> Command output section.
>>>>
>>>> packages using knitr need to have Suggests: knitr and VignetteBuilder:
>>>> knitr in the DESCRIPTION file; make these changes to both release and
>>>> devel branches, bumping the version as below in devel, and to 1.0.3 in
>>>> release.
>>>>
>>>> Bioconductor packages are *required* to have a 'real' vignette with
>>>> evaluated code chunks; the reviewer must have missed this part of the
>>>> review process. You'll need to update your vignette to this
>>>> specification, while remaining within the size and space limitations
>>>> in the Bioconductor guidelines
>>>>
>>>> http://bioconductor.org/developers/package-guidelines/#correctness
>>>>
>>>> Hope that helps, please don't hesitate to ask (preferably as a
>>>> subscribed member on the Bioc-devel mailing list) for any further
>>>> assistance.
>>>>
>>>> ISoLDE$ svn diff
>>>> Index: DESCRIPTION
>>>> ===================================================================
>>>> --- DESCRIPTION    (revision 120902)
>>>> +++ DESCRIPTION    (working copy)
>>>> @@ -1,7 +1,7 @@
>>>>  Package: ISoLDE
>>>>  Type: Package
>>>>  Title: Integrative Statistics of alleLe Dependent Expression
>>>> -Version: 1.1.2
>>>> +Version: 1.1.3
>>>>  Date: 2015-10-29
>>>>  Authors at R: c( person("Christelle", "Reynès", email =
>>>>          "christelle.reynes at igf.cnrs.fr", role = c("aut","cre")),
>>>> @@ -16,6 +16,7 @@
>>>>  Encoding: UTF-8
>>>>  License: GPL (>= 2.0)
>>>>  Depends: R (>= 3.3.0),graphics,grDevices,stats,utils
>>>> +Suggests: knitr
>>>>  URL: www.r-project.org
>>>>  LazyData: no
>>>>  NeedsCompilation: yes
>>>> @@ -26,3 +27,4 @@
>>>>          Sequencing, RNASeq, MultipleComparison, SNP,
>>>>          GeneticVariability, Epigenetics, MathematicalBiology,
>>>>          GeneRegulation
>>>> +VignetteBuilder: knitr
>>>>
>>>>
>>>> Martin
>>>>
>>>>
>>>> -------- Forwarded Message --------
>>>> Subject: Auto-discard notification
>>>> Date: Tue, 13 Sep 2016 15:17:52 +0200
>>>> From: bioc-devel-bounces at r-project.org
>>>> To: bioc-devel-owner at r-project.org
>>>>
>>>> The attached message has been automatically discarded.
>>>>
>>>>
>>>> This email message may contain legally privileged and/or confidential
>>>> information.  If you are not the intended recipient(s), or the
>>>> employee or agent responsible for the delivery of this message to the
>>>> intended recipient(s), you are hereby notified that any disclosure,
>>>> copying, distribution, or use of this email message is prohibited.  If
>>>> you have received this message in error, please notify the sender
>>>> immediately by e-mail and delete this email message from your
>>>> computer. Thank you.
>>>
>>
>>
>> This email message may contain legally privileged and/or confidential
>> information.  If you are not the intended recipient(s), or the
>> employee or agent responsible for the delivery of this message to the
>> intended recipient(s), you are hereby notified that any disclosure,
>> copying, distribution, or use of this email message is prohibited.  If
>> you have received this message in error, please notify the sender
>> immediately by e-mail and delete this email message from your
>> computer. Thank you.
>


This email message may contain legally privileged and/or...{{dropped:2}}