R devel - Jan 2018 - Best practices in developing package: From a single file

Mehmet,

That is a loaded topic, not unlikely other topics preoccupying us these days.

There is package.skeleton() in base R as you already mentioned. It drove me
bonkers that it creates packages which then fail R CMD check, so I wrote a
wrapper package (pkgKitten) with another helper function (kitten()) which
calls the base R helper and then cleans up it---but otherwise remains
faithful to it.

These days pkgKitten defaults to creating per-package top-level help page
that just references content from DESCRIPTION via a set of newer Rd macros as
I find that helps keeping them aligned. The most recent example of mine is
  https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd 
I use either this function or the RStudio template helper all the time.

And similarly, other people written similar helpers. You may get other pointers.

And every couple of months someone writes a new tutorial about how to write a
first package. Then social media goes gaga and we get half a dozen blog posts
where someone celebrates finding said tutorial, reading it and following
through with a new package. 

And many of us taught workshops on creating packages. There is a lot of
material out here, though lots of this material seems to be entirely ignorant
of what came before it.

And there has been lots, including Fritz's tutorial from a decade ago:

    https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
    https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf

So I'd recommend you just experiment and set up your own helpers. After all
the rule still holds: Anything you do more than three times should be a
function, and every function should be in a package. So customize _your_
function to create your package.

Dirk

-- 
http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org

In response to Duncan regarding the use of roxygen2 from the point of view
of a current user, I believe the issue he brings up is one of correlation
rather than causation.

Writing my first piece of R documentation was made much easier by using
roxygen2, and it shallowed the learning curve substantially.

What Duncan may be observing is a general tendency of roxygen2 users to
write overly concise documentation. However, I believe this to be caused by
an omitted variable - likely the tendency of roxygen2 users to want outputs
quickly. I can't see anything in roxygen2 that might suggest a causal link
but I'd be interested in hearing specific examples.

FWIW, I've also heard the same documentation criticism leveled at R in
general (mostly from Stata and MATLAB users).

Kenny

On Wed, Jan 31, 2018, 10:12 AM Dirk Eddelbuettel <edd at debian.org>
wrote:
>
> Mehmet,
>
> That is a loaded topic, not unlikely other topics preoccupying us these
> days.
>
> There is package.skeleton() in base R as you already mentioned. It drove me
> bonkers that it creates packages which then fail R CMD check, so I wrote a
> wrapper package (pkgKitten) with another helper function (kitten()) which
> calls the base R helper and then cleans up it---but otherwise remains
> faithful to it.
>
> These days pkgKitten defaults to creating per-package top-level help page
> that just references content from DESCRIPTION via a set of newer Rd macros
> as
> I find that helps keeping them aligned. The most recent example of mine is
>   https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
> I use either this function or the RStudio template helper all the time.
>
> And similarly, other people written similar helpers. You may get other
> pointers.
>
> And every couple of months someone writes a new tutorial about how to
> write a
> first package. Then social media goes gaga and we get half a dozen blog
> posts
> where someone celebrates finding said tutorial, reading it and following
> through with a new package.
>
> And many of us taught workshops on creating packages. There is a lot of
> material out here, though lots of this material seems to be entirely
> ignorant
> of what came before it.
>
> And there has been lots, including Fritz's tutorial from a decade ago:
>
>     https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
>     https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
>
> So I'd recommend you just experiment and set up your own helpers. After
all
> the rule still holds: Anything you do more than three times should be a
> function, and every function should be in a package. So customize _your_
> function to create your package.
>
> Dirk
>
> --
> http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
	[[alternative HTML version deleted]]

On 30/01/2018 4:30 PM, Kenny Bell wrote:
> In response to Duncan regarding the use of roxygen2 from the point of view
> of a current user, I believe the issue he brings up is one of correlation
> rather than causation.
Could be.  However, I think editing comments in a .R file is a bit 
harder than editing text in a .Rd file, so I think the format 
discourages editing.  I think it does make it easier to pass R CMD check 
the first time, but I don't think you should be satisfied with that.

What would probably change my mind would be a two-way (or multi-way) 
tool:  it takes input in Roxygen comments or Rd files (or something 
else), and produces another format.  Then I'd probably choose to write 
the first pass in Roxygen, and convert to Rd for editing.  Other people 
might go in the opposite direction.  Or someone might write a fancy 
WYSIWYG editor for people who like that style of editing.

A couple of years ago I was hoping someone would figure out a way to 
create help page input in R Markdown, but I think that's tricky because 
of the lack of semantic markup there.  There *was* a project last year 
to work on other input methods; I dropped out before it got very far, 
and I don't know its current status.
> 
> Writing my first piece of R documentation was made much easier by using
> roxygen2, and it shallowed the learning curve substantially.
I'm not completely up to date on Roxygen2 these days:  can you do some 
pages in Rd, others in Roxygen?  That's not quite as good as being able 
to switch back and forth, but it would allow you to start in Roxygen, 
then gradually move to Rd when editing there was easier.
> 
> What Duncan may be observing is a general tendency of roxygen2 users to
> write overly concise documentation. However, I believe this to be caused by
> an omitted variable - likely the tendency of roxygen2 users to want outputs
> quickly. I can't see anything in roxygen2 that might suggest a causal
link
> but I'd be interested in hearing specific examples.
I don't know about that.  *Everyone* wants output quickly.

Duncan Murdoch

> FWIW, I've also heard the same documentation criticism leveled at R in
> general (mostly from Stata and MATLAB users).
> 
> Kenny
> 
> On Wed, Jan 31, 2018, 10:12 AM Dirk Eddelbuettel <edd at debian.org>
wrote:
> 
>>
>> Mehmet,
>>
>> That is a loaded topic, not unlikely other topics preoccupying us these
>> days.
>>
>> There is package.skeleton() in base R as you already mentioned. It
drove me
>> bonkers that it creates packages which then fail R CMD check, so I
wrote a
>> wrapper package (pkgKitten) with another helper function (kitten())
which
>> calls the base R helper and then cleans up it---but otherwise remains
>> faithful to it.
>>
>> These days pkgKitten defaults to creating per-package top-level help
page
>> that just references content from DESCRIPTION via a set of newer Rd
macros
>> as
>> I find that helps keeping them aligned. The most recent example of mine
is
>>    https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
>> I use either this function or the RStudio template helper all the time.
>>
>> And similarly, other people written similar helpers. You may get other
>> pointers.
>>
>> And every couple of months someone writes a new tutorial about how to
>> write a
>> first package. Then social media goes gaga and we get half a dozen blog
>> posts
>> where someone celebrates finding said tutorial, reading it and
following
>> through with a new package.
>>
>> And many of us taught workshops on creating packages. There is a lot of
>> material out here, though lots of this material seems to be entirely
>> ignorant
>> of what came before it.
>>
>> And there has been lots, including Fritz's tutorial from a decade
ago:
>>
>>      https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
>>      https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
>>
>> So I'd recommend you just experiment and set up your own helpers.
After all
>> the rule still holds: Anything you do more than three times should be a
>> function, and every function should be in a package. So customize
_your_
>> function to create your package.
>>
>> Dirk
>>
>> --
>> http://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
> 
> 	[[alternative HTML version deleted]]
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

On 30/01/2018 4:12 PM, Dirk Eddelbuettel wrote:
> 
> Mehmet,
> 
> That is a loaded topic, not unlikely other topics preoccupying us these
days.
> 
> There is package.skeleton() in base R as you already mentioned. It drove me
> bonkers that it creates packages which then fail R CMD check, so I wrote a
> wrapper package (pkgKitten) with another helper function (kitten()) which
> calls the base R helper and then cleans up it---but otherwise remains
> faithful to it.
Failing R CMD check isn't a big deal:  you want to be reminded to edit 
those incomplete help files.  But I think I recall that you couldn't 
even build the package that package.skeleton() created, and that indeed 
would be irritating, especially if you had a lot of functions so you had 
a lot of cleanup to do.  I don't know if that's still true because I 
generally use RStudio to create the initial package structure rather 
than calling package.skeleton myself.

Duncan Murdoch
> 
> These days pkgKitten defaults to creating per-package top-level help page
> that just references content from DESCRIPTION via a set of newer Rd macros
as
> I find that helps keeping them aligned. The most recent example of mine is
>    https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
> I use either this function or the RStudio template helper all the time.
> 
> And similarly, other people written similar helpers. You may get other
pointers.
> 
> And every couple of months someone writes a new tutorial about how to write
a
> first package. Then social media goes gaga and we get half a dozen blog
posts
> where someone celebrates finding said tutorial, reading it and following
> through with a new package.
> 
> And many of us taught workshops on creating packages. There is a lot of
> material out here, though lots of this material seems to be entirely
ignorant
> of what came before it.
> 
> And there has been lots, including Fritz's tutorial from a decade ago:
> 
>      https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
>      https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
> 
> So I'd recommend you just experiment and set up your own helpers. After
all
> the rule still holds: Anything you do more than three times should be a
> function, and every function should be in a package. So customize _your_
> function to create your package.
> 
> Dirk
>

>> There is package.skeleton() in base R as you already mentioned. It
drove
>> me
>> bonkers that it creates packages which then fail R CMD check, so I
wrote a
>> wrapper package (pkgKitten) with another helper function (kitten())
which
>> calls the base R helper and then cleans up it---but otherwise remains
>> faithful to it.
>
>
> Failing R CMD check isn't a big deal:  you want to be reminded to edit
those
> incomplete help files.  But I think I recall that you couldn't even
build
> the package that package.skeleton() created, and that indeed would be
> irritating, especially if you had a lot of functions so you had a lot of
> cleanup to do.  I don't know if that's still true because I
generally use
> RStudio to create the initial package structure rather than calling
> package.skeleton myself.
Personally, I think the biggest problem with package.skeleton() is
that it assumes that the source of truth is objects in an environment.
This seems the wrong way around to me.

Hadley

-- 
http://hadley.nz