Logo Questions Linux Laravel Mysql Ubuntu Git Menu
HTML CSS JAVASCRIPT SQL PYTHON PHP BOOTSTRAP JAVA JQUERY R React Kotlin
 

What is the purpose difference between README and vignette in R package?

Tags:

readme

r

documentation

vignette

I have an R package on GitHub that I am about to submit to CRAN. Up to now, the package has had an extensive README.md document that shows:

  • examples of package core functions execution,
  • examples of package demo execution,
  • some benchmark results.

For the purposes of GitHub users, I thought that putting these to README.md is more appealing than vignette as it shows up when a user views the package's repo.

When I am at the point of moving the package to CRAN, I would like to have pretty much the same content as currently in README.md available in a form of a vignette.

Question: is it a correct way of acting to make an almost 1-1 copy of README.md into a vignette, keep both, update GitHub repo to have this vignette as well, and then submit as such to CRAN? Or: it would pose a duplication that should not take place? (then how should I proceed?)

like image 293
Marta Karas Avatar asked Dec 17 '18 03:12

Marta Karas

People also ask

How do I read a vignette in R?

To see the vignette for a specific package, use the argument, browseVignettes ("packagename"). Each vignette provides three things: the original source file, a readable HTML page or PDF, and a file of R code. You can read a specific vignette with vignette (x), and see its code with edit (vignette (x)).

What is a vignette?

A vignette is a long-form guide to your package. Function documentation is great if you know the name of the function you need, but it’s useless otherwise. A vignette is like a book chapter or an academic paper: it can describe the problem that your package is designed to solve, and then show the reader how to solve it.

What is the difference between a vignette and a function documentation?

Function documentation is great if you know the name of the function you need, but it’s useless otherwise. A vignette is like a book chapter or an academic paper: it can describe the problem that your package is designed to solve, and then show the reader how to solve it.

How do I see the vignette for a specific package?

To see the vignette for a specific package, use the argument, browseVignettes ("packagename"). Each vignette provides three things: the original source file, a readable HTML page or PDF, and a file of R code.

Video Answer

1 Answers

Yes, I think that is not uncommmon. You

  • have a README.md at GitHub as the 'public face' of the (source) package repo
  • want a package summary for which a vignette may serve well
  • may even end up with a package webite or summary

and the same markdown text might as well serve in all three instances.

In any event there is no rule against it. Also, in case you did not know, this would have been a good question for the dedicated and focused r-package-devel mailing list concerned with packaging.

like image 54
Dirk Eddelbuettel Avatar answered Oct 16 '22 09:10

Dirk Eddelbuettel
Sign in to Comment

Related questions

Select all rows which are duplicates except for one column
How to convert fitdistrplus::fitdist summary into tidy format?
Multiplying elements of a matrix depending on numbers and strings of the row names and column names (2)
Dynamic scoping questions in R
Xaringan Title Slide
Convert five-year data to annual data and calculate new records in R
How to subset your dataframe to only keep the first duplicate? [duplicate]
Is there a way to hide Trace Names in Plotly (specifically R)?
add_trace: control the color
Adjust font size to size of plot device
Reverse ggplot time scale
data plotted in ggplot to highcharter
Wrap long url line in R markdown
combining POSIXct gives wrong hours [duplicate]
Correct way to use here package with cronR scheduling
ggplot `scale_fill_manual()` alternate colors infinitely
How/When is the HOME environment variable set within R
Finding duplicates in a dataframe and returning count of each duplicate record
How to write files with Unix end of lines on R for Windows
How to change the units of difftime after computing the values, and not using units="xxx" when performing the calculations

Donate For Us

If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!