[Bioc-devel] jupyter notebooks as vignettes?

[Martin Morgan]

I'm forwarding a couple of messages from the support site.

I'd appreciate some discussion.

It seems like jupyter notebooks are becoming increasingly plausible as a 
possible vignette format, and I was wondering whether there is any real-world 
experience with these, including their pros and cons as vignettes. For instance...

Developer / build system

- Presumably these notebooks need to be run as part of the package check -- no 
sense distributed non-functional notebooks. Are there facilities for this, along 
the lines of a traditional vignette that builds and potentially generates errors 
during R and / or document processing?

- Are notebooks actually mature enough that, e.g., their format will not change 
dramatically?

End-user

- I guess most end users will get static, evaluated versions of the notebooks, 
unless they install python & friends. Is that right?

- Can the user easily obtain the equivalent of a Stangle'd vignette, i.e., a 
runnable R script?

- If a typical user only has access to a static version of the notebook, then 
what have we gained relative to traditional vignettes?

-------- Forwarded Message --------
Subject: 	[bioc] A: BiocCheck: REQUIRED: vignette sources in vignettes/
directory (for custom vignet
Date: 	Wed, 20 May 2015 16:32:24 -0000
From: 	Dan Tenenbaum [bioc] <noreply at bioconductor.org>
Reply-To: 	reply+9665d4a8+code at bioconductor.org
To: 	mtmorgan at fhcrc.org



Activity on a post you are following on support.bioconductor.org
<https://support.bioconductor.org>

User Dan Tenenbaum <https://support.bioconductor.org/u/4256/> wrote Answer:
BiocCheck: REQUIRED: vignette sources in vignettes/ directory (for custom
vignettebuilder) <https://support.bioconductor.org/p/67884/#67885>:

BTW, questions about package development and submission should go to the
bioc-devel mailing list <http://bioconductor.org/help/support/#bioc-devel>.

We don't yet have a policy about .ipynb vignettes and we'd have to make sure the
build system is capable of building them. However, I would ignore the error for
now and you can discuss it with your reviewer when you submit the package.

--------------------------------------------------------------------------------

-------- Forwarded Message --------
Subject: 	[bioc] BiocCheck: REQUIRED: vignette sources in vignettes/ directory
(for custom vignettebuilder)
Date: 	Wed, 20 May 2015 16:29:49 -0000
From: 	flying-sheep [bioc] <noreply at bioconductor.org>
Reply-To: 	reply+c01911bc+code at bioconductor.org
To: 	mtmorgan at fhcrc.org



Activity on a post you are following on support.bioconductor.org
<https://support.bioconductor.org>

User flying-sheep <https://support.bioconductor.org/u/7779/> wrote Question:
BiocCheck: REQUIRED: vignette sources in vignettes/ directory (for custom
vignettebuilder) <https://support.bioconductor.org/p/67884/>:

I’m using a .ipynb notebook as source for my Vignette, so I created a Vignette
engine inside my package to build it.

That one registers a the necessary extensions, and R CMD build obediently
creates a vignette from the .ipynb file.

Yet R CMD BiocCheck still says `REQUIRED: vignette sources in vignettes/
directory`. should I ignore that when submitting my package, or will the
bioconductor people have to fix that check beforehand?

--------------------------------------------------------------------------------

You may reply via email or visit https://support.bioconductor.org/p/67884/