[Rd] Strategies for keeping autogenerated .Rd files out of a Git tree

[Gábor Csárdi]

On Fri, Dec 13, 2013 at 6:03 AM, Kirill Müller
<kirill.mueller at ivt.baug.ethz.ch> wrote:
> 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.

I set my CI, so that it does not allow concurrent builds from the same
job. So there are no race conditions. This is probably possible with
Travis, I don't know.

> How do you handle branches?

So far I didn't, and only pushed back "main" branch. But you can just
push back to different branches. In this case I would probably create
another repo, and have the same branches in both in the "source" repo
and the "publish" repo.

> It would be really great to be able to execute custom R code before
> building. Perhaps in a PreBuild: section in DESCRIPTION?

I am just using make to create the package. This creates all
autogenerated files and then calls R PKG build.

Another option for this whole problem is not using github at all, but
setting up a CRAN-like repository, and make the CI publish the built
and checked packages there.

Gabor

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