[Rd] Strategies for keeping autogenerated .Rd files out of a Git tree
Kirill Müller
kirill.mueller at ivt.baug.ethz.ch
Fri Dec 13 21:43:59 CET 2013
Thanks a lot. This would indeed solve the problem. I'll try mkdist today ;-)
Is the NEWS file parsed before of after mkdist has been executed?
Would you be willing to share the code for the infrastructure, perhaps
on GitHub?
-Kirill
On 12/13/2013 09:14 PM, Simon Urbanek wrote:
> FWIW this is essentially what RForge.net provides. Each GitHub commit triggers a build (branches are supported as the branch info is passed in the WebHook) which can be either "classic" R CMD build or a custom shell script (hence you can do anything you want). The result is a tar ball (which includes the generated files) and that tar ball gets published in the R package repository. R CMD check is run as well on the tar ball and the results are published.
> This way you don't need devtools, users can simply use install.packages() without requiring any additional tools.
>
> There are some talks about providing the above as a cloud service, so that anyone can run and/or use it.
>
> Cheers,
> Simon
>
>
> On Dec 13, 2013, at 8:51 AM, Kirill Müller <kirill.mueller at ivt.baug.ethz.ch> wrote:
>
>> On 12/13/2013 12:50 PM, Romain Francois wrote:
>>> Pushing back to github is not so difficult. See e.g
>>> http://blog.r-enthusiasts.com/2013/12/04/automated-blogging.html
>> Thanks for the writeup, I'll try this. Perhaps it's better to push the
>> results of `R CMD build`, though.
>>> You can manage branches easily in travis. You could for example decide
>>> to do something different if you are on the master branch ...
>> That's right. But then no .Rd files are built when I'm on a branch, so I
>> can't easily preview the result.
>>
>> The ideal situation would be:
>>
>> 1. I manage only R source files on GitHub, not Rd files, NAMESPACE nor
>> the "Collate" section of DESCRIPTION. Machine-readable instructions on
>> how to build those are provided with the package.
>> 2. Anyone can install from GitHub using devtools::install_github(). This
>> also should work for branches, forks and pull requests.
>> 3. I can build the package so that the result can be accepted by CRAN.
>>
>> The crucial point on that list is point 2, the others I can easily solve
>> myself.
>>
>> The way I see it, point 2 can be tackled by extending devtools or
>> extending the ways packages are built. Extending devtools seems to be
>> the inferior approach, although, to be honest, I'd be fine with that as
>> well.
>>
>>
>> -Kirill
>>
>>> Romain
>>>
>>> Le 13 déc. 2013 à 12:03, Kirill Müller
>>> <kirill.mueller at ivt.baug.ethz.ch
>>> <mailto:kirill.mueller at ivt.baug.ethz.ch>> a écrit :
>>>
>>>> Gabor
>>>>
>>>> I agree with you. There's Travis CI, and r-travis -- an attempt to
>>>> integrate R package testing with Travis. Pushing back to GitHub is
>>>> possible, but the setup is somewhat difficult. Also, this can be
>>>> subject to race conditions because each push triggers a test run and
>>>> they can happen in parallel even for the same repository. How do you
>>>> handle branches?
>>>>
>>>> It would be really great to be able to execute custom R code before
>>>> building. Perhaps in a PreBuild: section in DESCRIPTION?
>>>>
>>>>
>>>> Cheers
>>>>
>>>> Kirill
>>>>
>>>>
>>>> On 12/12/2013 02:21 AM, Gábor Csárdi wrote:
>>>>> Hi,
>>>>>
>>>>> this is maybe mostly a personal preference, but I prefer not to put
>>>>> generated files in the vc repository. Changes in the generated files,
>>>>> especially if there is many of them, pollute the diffs and make them
>>>>> less useful.
>>>>>
>>>>> If you really want to be able to install the package directly from
>>>>> github, one solution is to
>>>>> 1. create another repository, that contains the complete generated
>>>>> package, so that install_github() can install it.
>>>>> 2. set up a CI service, that can download the package from github,
>>>>> build the package or the generated files (check the package, while it
>>>>> is at it), and then push the build stuff back to github.
>>>>> 3. set up a hook on github, that invokes the CI after each commit.
>>>>>
>>>>> I have used this setup in various projects with jenkins-ci and it
>>>>> works well. Diffs are clean, the package is checked and built
>>>>> frequently, and people can download it without having to install the
>>>>> tools that generate the generated files.
>>>>>
>>>>> The only downside is that you need to install a CI, so you need a
>>>>> "server" for that. Maybe you can do this with travis-ci, maybe not, I
>>>>> am not familiar with it that much.
>>>>>
>>>>> Best,
>>>>> Gabor
>>>>>
>>>>> On Wed, Dec 11, 2013 at 7:39 PM, Kirill Müller
>>>>> <kirill.mueller at ivt.baug.ethz.ch
>>>>> <mailto:kirill.mueller at ivt.baug.ethz.ch>> wrote:
>>>>>> Hi
>>>>>>
>>>>>> Quite a few R packages are now available on GitHub long before they
>>>>>> appear
>>>>>> on CRAN, installation is simple thanks to devtools::install_github().
>>>>>> However, it seems to be common practice to keep the .Rd files (and
>>>>>> NAMESPACE
>>>>>> and the Collate section in the DESCRIPTION) in the Git tree, and to
>>>>>> manually
>>>>>> update it, even if they are autogenerated from the R code by
>>>>>> roxygen2. This
>>>>>> requires extra work for each update of the documentation and also binds
>>>>>> package development to a specific version of roxygen2 (because
>>>>>> otherwise
>>>>>> lots of bogus changes can be added by roxygenizing with a different
>>>>>> version).
>>>>>>
>>>>>> What options are there to generate the .Rd files during
>>>>>> build/install? In
>>>>>> https://github.com/hadley/devtools/issues/43 the issue has been
>>>>>> discussed,
>>>>>> perhaps it can be summarized as follows:
>>>>>>
>>>>>> - The devtools package is not the right place to implement
>>>>>> roxygenize-before-build
>>>>>> - A continuous integration service would be better for that, but
>>>>>> currently
>>>>>> there's nothing that would be easy to use
>>>>>> - Roxygenizing via src/Makefile could work but requires further
>>>>>> investigation and an installation of Rtools/xcode on Windows/OS X
>>>>>>
>>>>>> Especially the last point looks interesting to me, but since this
>>>>>> is not
>>>>>> widely used there must be pitfalls I'm not aware of. The general
>>>>>> idea would
>>>>>> be:
>>>>>>
>>>>>> - Place code that builds/updates the .Rd and NAMESPACE files into
>>>>>> src/Makefile
>>>>>> - Users installing the package from source will require infrastructure
>>>>>> (Rtools/make)
>>>>>> - For binary packages, the .Rd files are already generated and
>>>>>> added to the
>>>>>> .tar.gz during R CMD build before they are submitted to
>>>>>> CRAN/WinBuilder, and
>>>>>> they are also generated (in theory) by R CMD build --binary
>>>>>>
>>>>>> I'd like to hear your opinion on that. I have also found a thread
>>>>>> on package
>>>>>> development workflow
>>>>>> (https://stat.ethz.ch/pipermail/r-devel/2011-September/061955.html) but
>>>>>> there was nothing on un-versioning .Rd files.
>>>>>>
>>>>>>
>>>>>> Cheers
>>>>>>
>>>>>> Kirill
>>>>>>
>>>>>> ______________________________________________
>>>>>> R-devel at r-project.org <mailto:R-devel at r-project.org> mailing list
>>>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>> --
>>>> _________________________________________________
>>>> ETH Zürich
>>>> Institute for Transport Planning and Systems
>>>> HIL F 32.2
>>>> Wolfgang-Pauli-Str. 15
>>>> 8093 Zürich
>>>>
>>>> Phone: +41 44 633 33 17
>>>> Fax: +41 44 633 10 57
>>>> Secretariat: +41 44 633 31 05
>>>> E-Mail: kirill.mueller at ivt.baug.ethz.ch
>>>> <mailto:kirill.mueller at ivt.baug.ethz.ch>
>>>>
>>>> ______________________________________________
>>>> R-devel at r-project.org <mailto:R-devel at r-project.org> mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>> --
>> _________________________________________________
>> ETH Zürich
>> Institute for Transport Planning and Systems
>> HIL F 32.2
>> Wolfgang-Pauli-Str. 15
>> 8093 Zürich
>>
>> Phone: +41 44 633 33 17
>> Fax: +41 44 633 10 57
>> Secretariat: +41 44 633 31 05
>> E-Mail: kirill.mueller at ivt.baug.ethz.ch
>>
>>
>> [[alternative HTML version deleted]]
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
--
_________________________________________________
ETH Zürich
Institute for Transport Planning and Systems
HIL F 32.2
Wolfgang-Pauli-Str. 15
8093 Zürich
Phone: +41 44 633 33 17
Fax: +41 44 633 10 57
Secretariat: +41 44 633 31 05
E-Mail: kirill.mueller at ivt.baug.ethz.ch
More information about the R-devel
mailing list