Re: [R-pkg-devel] roxygen style documentation for data sets

2023-09-21 Thread Duncan Murdoch 
I just found a couple of packages with add-ins that do something like 
this:  sinew (on CRAN) and docthis on Github at


 https://github.com/mdlincoln/docthis

I think neither of them is quite as smooth as the `Code | Insert Roxygen 
Skeleton` menu item in RStudio, but both do handle dataframes, and it 
doesn't.


Duncan Murdoch

On 21/09/2023 4:30 p.m., Michael L Friendly wrote:

I am an RStudio user, and I could see this as a plugin somewhere, but I don't 
want to create a package just for this.

I'd rather that my code could be adopted somewhere in the framework of 
devtools/usethis/ ...

It's so obvious that this tool should be there somewhere, particularly since 
RStudio makes it hard to work with .Rd files, except those generated by 
devtools (which shouldn't be
edited). E.g., I have many legacy .Rd files for data. I can't select example 
code and click Run, as one can do with roxygen documentation in .R files.

-Michael

-Original Message-
From: Duncan Murdoch 
Sent: Thursday, September 21, 2023 3:58 PM
To: Michael L Friendly ; r-package-devel@r-project.org
Subject: Re: [R-pkg-devel] roxygen style documentation for data sets

Hi Michael.

I don't know if you're an RStudio user, but this seems ideal as the basis for 
an RStudio plug-in.  Just install it, then when you want to generate docs for 
some dataset defined in R code, move to the start of the definition and hit 
some hot key to insert the documentation skeleton ahead of the data definition.

Duncan Murdoch

On 21/09/2023 12:33 p.m., Michael L Friendly wrote:

I have many datasets in a some of my packages, and always used 
`utils::promptData()` to generate the skeleton of a man/data.Rd file.
Now that I've switched to roxygen style, I have found no simple
equivalent. In fact, with RStudio tools for generating documentation for 
functions, it is surprising that documenting data has been overlooked.

I solved this problem by simply editing `utils::promptData()` to replace .Rd 
style with equivalent roxygen tags.

The result in now in a gist,
https://gist.github.com/friendly/14f3ee1464213bb0b9fbcb489468383b
I called this function `use_data_doc()`, because I thought it would be a 
welcome addition to the usethis package.

I hope that someone on this list can advise how to make such a function 
available to all R package developers.

-Michael

---
Michael Friendly Email: friendly AT yorku DOT ca
Professor, Psychology Dept.
York University  Voice: 416 736-2100 x66249
4700 Keele StreetWeb: http://www.datavis.ca<http://www.datavis.ca/> | 
@datavisFriendly
Toronto, ONT  M3J 1P3 CANADA


[[alternative HTML version deleted]]

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel




__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] roxygen style documentation for data sets

2023-09-21 Thread Jeff Newmiller via R-package-devel 
I thought roxygen supported documenting NULL constants for data.

I do think roxygen ought to be able to co-exist with Rd files... but the claim 
that documenting data requires Rd files smells fishy to me.

On September 21, 2023 1:30:11 PM PDT, Michael L Friendly  
wrote:
>I am an RStudio user, and I could see this as a plugin somewhere, but I don't 
>want to create a package just for this.
>
>I'd rather that my code could be adopted somewhere in the framework of 
>devtools/usethis/ ... 
>
>It's so obvious that this tool should be there somewhere, particularly since 
>RStudio makes it hard to work with .Rd files, except those generated by 
>devtools (which shouldn't be
>edited). E.g., I have many legacy .Rd files for data. I can't select example 
>code and click Run, as one can do with roxygen documentation in .R files.
>
>-Michael
>
>-Original Message-
>From: Duncan Murdoch  
>Sent: Thursday, September 21, 2023 3:58 PM
>To: Michael L Friendly ; r-package-devel@r-project.org
>Subject: Re: [R-pkg-devel] roxygen style documentation for data sets
>
>Hi Michael.
>
>I don't know if you're an RStudio user, but this seems ideal as the basis for 
>an RStudio plug-in.  Just install it, then when you want to generate docs for 
>some dataset defined in R code, move to the start of the definition and hit 
>some hot key to insert the documentation skeleton ahead of the data definition.
>
>Duncan Murdoch
>
>On 21/09/2023 12:33 p.m., Michael L Friendly wrote:
>> I have many datasets in a some of my packages, and always used 
>> `utils::promptData()` to generate the skeleton of a man/data.Rd file.
>> Now that I've switched to roxygen style, I have found no simple 
>> equivalent. In fact, with RStudio tools for generating documentation for 
>> functions, it is surprising that documenting data has been overlooked.
>> 
>> I solved this problem by simply editing `utils::promptData()` to replace .Rd 
>> style with equivalent roxygen tags.
>> 
>> The result in now in a gist, 
>> https://gist.github.com/friendly/14f3ee1464213bb0b9fbcb489468383b
>> I called this function `use_data_doc()`, because I thought it would be a 
>> welcome addition to the usethis package.
>> 
>> I hope that someone on this list can advise how to make such a function 
>> available to all R package developers.
>> 
>> -Michael
>> 
>> ---
>> Michael Friendly Email: friendly AT yorku DOT ca
>> Professor, Psychology Dept.
>> York University  Voice: 416 736-2100 x66249
>> 4700 Keele StreetWeb: http://www.datavis.ca<http://www.datavis.ca/> | 
>> @datavisFriendly
>> Toronto, ONT  M3J 1P3 CANADA
>> 
>> 
>>  [[alternative HTML version deleted]]
>> 
>> __
>> R-package-devel@r-project.org mailing list 
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
>__
>R-package-devel@r-project.org mailing list
>https://stat.ethz.ch/mailman/listinfo/r-package-devel

-- 
Sent from my phone. Please excuse my brevity.

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] roxygen style documentation for data sets

2023-09-21 Thread Michael L Friendly 
I am an RStudio user, and I could see this as a plugin somewhere, but I don't 
want to create a package just for this.

I'd rather that my code could be adopted somewhere in the framework of 
devtools/usethis/ ... 

It's so obvious that this tool should be there somewhere, particularly since 
RStudio makes it hard to work with .Rd files, except those generated by 
devtools (which shouldn't be
edited). E.g., I have many legacy .Rd files for data. I can't select example 
code and click Run, as one can do with roxygen documentation in .R files.

-Michael

-Original Message-
From: Duncan Murdoch  
Sent: Thursday, September 21, 2023 3:58 PM
To: Michael L Friendly ; r-package-devel@r-project.org
Subject: Re: [R-pkg-devel] roxygen style documentation for data sets

Hi Michael.

I don't know if you're an RStudio user, but this seems ideal as the basis for 
an RStudio plug-in.  Just install it, then when you want to generate docs for 
some dataset defined in R code, move to the start of the definition and hit 
some hot key to insert the documentation skeleton ahead of the data definition.

Duncan Murdoch

On 21/09/2023 12:33 p.m., Michael L Friendly wrote:
> I have many datasets in a some of my packages, and always used 
> `utils::promptData()` to generate the skeleton of a man/data.Rd file.
> Now that I've switched to roxygen style, I have found no simple 
> equivalent. In fact, with RStudio tools for generating documentation for 
> functions, it is surprising that documenting data has been overlooked.
> 
> I solved this problem by simply editing `utils::promptData()` to replace .Rd 
> style with equivalent roxygen tags.
> 
> The result in now in a gist, 
> https://gist.github.com/friendly/14f3ee1464213bb0b9fbcb489468383b
> I called this function `use_data_doc()`, because I thought it would be a 
> welcome addition to the usethis package.
> 
> I hope that someone on this list can advise how to make such a function 
> available to all R package developers.
> 
> -Michael
> 
> ---
> Michael Friendly Email: friendly AT yorku DOT ca
> Professor, Psychology Dept.
> York University  Voice: 416 736-2100 x66249
> 4700 Keele StreetWeb: http://www.datavis.ca<http://www.datavis.ca/> | 
> @datavisFriendly
> Toronto, ONT  M3J 1P3 CANADA
> 
> 
>   [[alternative HTML version deleted]]
> 
> __
> R-package-devel@r-project.org mailing list 
> https://stat.ethz.ch/mailman/listinfo/r-package-devel

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] roxygen style documentation for data sets

2023-09-21 Thread John Fox 

Hi Michael,

I'm no license expert either, but I too believe that while a 
GPL-licensed package can incorporate MIT-licensed code, an MIT-licensed 
package can't incorporate GPL-licensed code.


One solution, I think, would be to put your use_data_doc() in a separate 
GPL-licensed package, which then could be specified as a dependency of 
usethis. Of course, the usethis developers would have to agree.


I hope this helps,
 John


On 2023-09-21 12:33 p.m., Michael L Friendly wrote:

Caution: External email.


I have many datasets in a some of my packages, and always used 
`utils::promptData()` to generate the skeleton of a man/data.Rd file.
Now that I've switched to roxygen style, I have found no simple equivalent. In 
fact, with RStudio tools for generating documentation
for functions, it is surprising that documenting data has been overlooked.

I solved this problem by simply editing `utils::promptData()` to replace .Rd 
style with equivalent roxygen tags.

The result in now in a gist, 
https://gist.github.com/friendly/14f3ee1464213bb0b9fbcb489468383b
I called this function `use_data_doc()`, because I thought it would be a 
welcome addition to the usethis package.

I hope that someone on this list can advise how to make such a function 
available to all R package developers.

-Michael

---
Michael Friendly Email: friendly AT yorku DOT ca
Professor, Psychology Dept.
York University  Voice: 416 736-2100 x66249
4700 Keele StreetWeb: http://www.datavis.ca | 
@datavisFriendly
Toronto, ONT  M3J 1P3 CANADA


 [[alternative HTML version deleted]]

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel


__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] roxygen style documentation for data sets

2023-09-21 Thread Duncan Murdoch 

Hi Michael.

I don't know if you're an RStudio user, but this seems ideal as the 
basis for an RStudio plug-in.  Just install it, then when you want to 
generate docs for some dataset defined in R code, move to the start of 
the definition and hit some hot key to insert the documentation skeleton 
ahead of the data definition.


Duncan Murdoch

On 21/09/2023 12:33 p.m., Michael L Friendly wrote:

I have many datasets in a some of my packages, and always used 
`utils::promptData()` to generate the skeleton of a man/data.Rd file.
Now that I've switched to roxygen style, I have found no simple equivalent. In 
fact, with RStudio tools for generating documentation
for functions, it is surprising that documenting data has been overlooked.

I solved this problem by simply editing `utils::promptData()` to replace .Rd 
style with equivalent roxygen tags.

The result in now in a gist, 
https://gist.github.com/friendly/14f3ee1464213bb0b9fbcb489468383b
I called this function `use_data_doc()`, because I thought it would be a 
welcome addition to the usethis package.

I hope that someone on this list can advise how to make such a function 
available to all R package developers.

-Michael

---
Michael Friendly Email: friendly AT yorku DOT ca
Professor, Psychology Dept.
York University  Voice: 416 736-2100 x66249
4700 Keele StreetWeb: http://www.datavis.ca | 
@datavisFriendly
Toronto, ONT  M3J 1P3 CANADA


[[alternative HTML version deleted]]

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel


__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] roxygen style documentation for data sets

2023-09-21 Thread Michael L Friendly 
Yes, if usethis is the most useful place for this to be, I suppose I should 
first flag this as an issue, and then issue a PR for my code.

I don't understand the fine distinctions between GPL-2 and MIT licensed code.

Perhaps some other developers can chime in here.

-Michael

-Original Message-
From: Ivan Krylov  
Sent: Thursday, September 21, 2023 1:37 PM
To: Michael L Friendly 
Cc: r-package-devel@r-project.org
Subject: Re: [R-pkg-devel] roxygen style documentation for data sets

В Thu, 21 Sep 2023 16:33:35 +
Michael L Friendly  пишет:

> I called this function `use_data_doc()`, because I thought it would be 
> a welcome addition to the usethis package.
> 
> I hope that someone on this list can advise how to make such a 
> function available to all R package developers.

Perhaps a pull request to https://github.com/r-lib/usethis/pulls ?

Should this function be considered a work derived from R? If yes, then (in my 
non-lawyer opinion) it retains its ownership by R Core and being licensed under 
GPL-2, which may be a problem for MIT-licensed usethis.

--
Best regards,
Ivan
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

Re: [R-pkg-devel] roxygen style documentation for data sets

2023-09-21 Thread Ivan Krylov 
В Thu, 21 Sep 2023 16:33:35 +
Michael L Friendly  пишет:

> I called this function `use_data_doc()`, because I thought it would
> be a welcome addition to the usethis package.
> 
> I hope that someone on this list can advise how to make such a
> function available to all R package developers.

Perhaps a pull request to https://github.com/r-lib/usethis/pulls ?

Should this function be considered a work derived from R? If yes, then
(in my non-lawyer opinion) it retains its ownership by R Core and being
licensed under GPL-2, which may be a problem for MIT-licensed usethis.

-- 
Best regards,
Ivan

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

[R-pkg-devel] roxygen style documentation for data sets

2023-09-21 Thread Michael L Friendly 
I have many datasets in a some of my packages, and always used 
`utils::promptData()` to generate the skeleton of a man/data.Rd file.
Now that I've switched to roxygen style, I have found no simple equivalent. In 
fact, with RStudio tools for generating documentation
for functions, it is surprising that documenting data has been overlooked.

I solved this problem by simply editing `utils::promptData()` to replace .Rd 
style with equivalent roxygen tags.

The result in now in a gist, 
https://gist.github.com/friendly/14f3ee1464213bb0b9fbcb489468383b
I called this function `use_data_doc()`, because I thought it would be a 
welcome addition to the usethis package.

I hope that someone on this list can advise how to make such a function 
available to all R package developers.

-Michael

---
Michael Friendly Email: friendly AT yorku DOT ca
Professor, Psychology Dept.
York University  Voice: 416 736-2100 x66249
4700 Keele StreetWeb: http://www.datavis.ca | 
@datavisFriendly
Toronto, ONT  M3J 1P3 CANADA


[[alternative HTML version deleted]]

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel