READMEs using .Rmd/.ipynb?

[mschubert]

The couple of READMEs we have got now highlight some functionality of the modules they are in.

Does it make sense to have .Rmd files instead that generate those READMEs to showcase functionality?

Advantages

• functionality can be checked by re-generating the .mds
• we'd have some high-level docs for "type x and y comes out"
• could also incorporate plots

Disadvantages

• we version-control an automatically generated file (this is minor) and possibly images

[barzine]

For the disadvantage point: do you really need to keep the md file?

[mschubert]

I'd want the docs to be visible in the repository, and Github renders .md but not .Rmd.

So yes, I think the .mds are necessary.

[barzine]

Well Github renders my .Rmd pretty fine in my case. Or I don't understand what you mean.
On side note, I have the same behaviour with Readme.md and Readme.Rmd (Github displays it on the first page)
The only thing would be that the expected result would have to be added as a comment or something

[mschubert]

Interesting, I didn't know.

However, it won't be able to show the result of R commands. If the READMEs are there to showcase functionality, it could never show the output. This kind of defeats the purpose.

[barzine]

Ok, I am probably slow to understand what you want: you want to be able to showcase the functionality, right?

So why can't you just add the expected results in another chunk instead with echo=FALSE and eval=FALSE? In the example I provided, the first chunk is defined as :

### 

but you can still see it.

Then, the Rmd can be used as a checking tool as well (which was the first reason you wanted to shift to .Rmd, no?)

[mschubert]

@klmr @barzine, what do you think of docs using ipynbs?

advantages

• can host text, code, graphics, etc.
• is both a static reference and executable
• can be used to test if examples still produce the right results

disadvantages

• frequent updates or graphics will increase repository size

[klmr]

I’ve never used Jupyter, if the R integration isn’t too convoluted (such as having to wrap every R call into a Python wrapper …), I have no objections.

[mschubert]

After installing the kernel and a couple of packages, it's just selecting R from a dropdown menu.

[barzine]

Just have seen this.
Never used ipynbs myself and very eager to learn about any new method that would help with the reporting.

This seems pretty nice. Can you confirm how it behaves with an extensive use?

[mschubert]

I haven't used them extensively, but so far they are working well.