Skip to content

[Bioc-devel] Missing vignette on my BioConductor page

4 messages · Marine Rohmer, Martin Morgan

Original
Marine Rohmer
# 
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?

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 :
-------------- next part --------------
A non-text attachment was scrubbed...
Name: vignette.pdf
Type: application/pdf
Size: 231509 bytes
Desc: not available
URL: <https://stat.ethz.ch/pipermail/bioc-devel/attachments/20160914/c331c99d/attachment-0001.pdf>
Martin Morgan
#
On 09/14/2016 08:49 AM, Marine Rohmer wrote:
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
This email message may contain legally privileged and/or...{{dropped:2}}
2 days later
Marine Rohmer
# 
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?

Regards,

Marine R.

Le 14/09/2016 ? 14:59, Martin Morgan a ?crit :
Martin Morgan
#
On 09/16/2016 10:02 AM, Marine Rohmer wrote:
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
This email message may contain legally privileged and/or...{{dropped:2}}