5

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?)

Marta Karas
  • 4,967
  • 10
  • 47
  • 77
  • I'd propose an alternative - use `library(pkgdown)` to create a website for you package. It builds the site from both your README and your vignette and hosts it on github pages. For example, take my `mapdeck` library - [here is the github readme](https://github.com/SymbolixAU/mapdeck#mapdeck), and here is the [`pkgdown site`](https://symbolixau.github.io/mapdeck/index.html), where the vignette is now the "getting started" page – SymbolixAU Dec 17 '18 at 03:16
  • Well, not reallty as it does not help the _user of the package who wants local resources_. An external website requires connectivity. If you read _Writing R Extensions_ carefully enough to get the _spirit_ of the document I feel you would agree that external resources, as common as they may be with some groups of developers, are what R Core first described. – Dirk Eddelbuettel Dec 17 '18 at 03:18
  • Thank you so much for the hint about `pkgdown `! I did not know about it, and I find it useful! – Marta Karas Dec 17 '18 at 03:19

1 Answers1

5

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.

Dirk Eddelbuettel
  • 360,940
  • 56
  • 644
  • 725
  • That is a wonderful answer! Hint about `r-package-devel` much appreciated. Thanks! – Marta Karas Dec 17 '18 at 03:18
  • 1
    You are very welcome -- feel free to accept the answer. I am also one of the founders/admins of that list and of the people who may approve your first post (b/c spam) after which you're free to post more :) – Dirk Eddelbuettel Dec 17 '18 at 03:19