search

rOpenGov / fmi

Finnish Meteorological Institute open data API R client
Other
10 stars 7 forks source link

Autogenerated content #7

Closed torsti closed 8 years ago

torsti commented 8 years ago

I'm still new to proper R packaging and not entirely familiar with the build process, but could we automate the Roxygen2 step and remove generated content from the repository?

jlehtoma commented 8 years ago

fmi indeed uses roxygen2 to autogenerate the documentation in man folder. If the package is properly roxygenized (and I think it is), there is never need to edit to content of man directly (in fact, you shouldn't). However, man is absolutely needed for R's help functionality to work so it shouldn't be removed. roxygen2 is essentially best described as a pre-processor such as Sphinx for Python.

roxygen2 will also automatically update the NAMESPACE file which is used to handle package exports and imports.

The bits used by roxygen2 are the ones directly preceding each function/class/method in the code files. Hadley Wickham has written an excellent introduction to R packages, I really recommend taking a look at that. Documentation with roxygen2 can be found in section Object documentation. I also recommend using R-Studio for everything, it has nice additional functionality for builds/checks/tests/documentation.

torsti commented 8 years ago

I've worked a little bit with roxygen2 trying to get rstan models packaged. I just wonder if we could invoke it from R's build system or manually, because the content is not edited by hand, so there's no need to have it tracked except to simplify the build process from the command line. Rstan uses a weird trick of calling roxygen2 from the cleanup files, but that is a somewhat ugly hack.

I've only been reading the official R and roxygen2 documentation, so Hadley's book is a great tip, thanks!

jlehtoma commented 8 years ago

Right, sorry! I misunderstood you. So you mean not having the generated Rd-files tracked by git? I'm not 100% sure about it either, but it could be that e.g. devtools::install_github() doesn't automatically invoke roxygen2::roxygenize() in which case there are no docs available. For CRAN submission, Rd-files are needed as well.

torsti commented 8 years ago

Exactly. And those are my question marks concerning the build process also. Can we remove them from the repo without breaking e.g. install_github or complicating CRAN submissions? The latter shouldn't be a problem, for sure they don't take the package directly from a repo?!

The rstan trick might work, as they got the package onto CRAN and it works with install_github too.

jlehtoma commented 8 years ago

Exactly. And those are my question marks concerning the build process also. Can we remove them from the repo without breaking e.g. install_github or complicating CRAN submissions? The latter shouldn't be a problem, for sure they don't take the package directly from a repo?!

No, they don't. For CRAN the Rd-files can be generated on need basis.

The rstan trick might work, as they got the package onto CRAN and it works with install_github too.

Sure, but is there really any major drawback of having the Rd-files in git? It is a bit annoying that e.g. R CMD BUILD (or the RStudio counterpart) doesn't invoke roxygenize automatically and you will have to remember to do yourself. On the other hand, roxygen2 documentation markup constantly has errors and problems (particularly if there is OOP involved). It's better to catch these early. So IMHO if there is a way to trigger building docs for e.g. install_github(), by all means.

antagomir commented 8 years ago

Imo it is better to keep the man files in github for the above mentioned reasons. Removing them may cause more confusion than keeping them there.

torsti commented 8 years ago

Though I dislike it for git-aesthetic reasons, this is definitely not high priority.

Let us come back to this only if it seems to bring some benefits or if there is some major refactoring of how the builds are done for other reasons.