R devel - Sep 2011 - Please explain your workflow from R code -> package -> R code -> package

Hi,

I'm asking another one of those questions that would be obvious if I
could watch your work while you do it.

I'm having trouble understanding the workflow of code and package
maintenance.

Stage 1.  Make some R functions in a folder.  This is in a Subversion repo

R/trunk/myproject

Stage 2. Make a package:

After the package.skeleton, and R check, I have a new folder with the
project in it,

R/trunk/myproject/mypackage
  DESCRIPTION
  man
  R

I to into the man folder and manually edit the Rd files. I don't
change anything in the R folder because I think it is OK so far.

And eventually I end up with a tarball mypackage_1.0.tar.gz.

Stage 3. How to make the round trip? I add more R code, and
re-generate a package.

package.skeleton obliterates the help files I've already edited.

So keeping the R code in sync with the documentation appears to be a hassle.

In other languages, I've seen to write the documentation inside the
code files and then post-process to make the documentation.  Is there
a similar thing for R, to unify the R code development and
documentation/package-making process?

pj

-- 
Paul E. Johnson
Professor, Political Science
1541 Lilac Lane, Room 504
University of Kansas

On Fri, Sep 9, 2011 at 11:38 AM, Paul Johnson <pauljohn32 at gmail.com>
wrote:
> Hi,
>
> I'm asking another one of those questions that would be obvious if I
> could watch your work while you do it.
>
> I'm having trouble understanding the workflow of code and package
maintenance.
>
> Stage 1. ?Make some R functions in a folder. ?This is in a Subversion repo
>
> R/trunk/myproject
>
> Stage 2. Make a package:
>
> After the package.skeleton, and R check, I have a new folder with the
> project in it,
>
> R/trunk/myproject/mypackage
> ?DESCRIPTION
> ?man
> ?R
>
> I to into the man folder and manually edit the Rd files. I don't
> change anything in the R folder because I think it is OK so far.
>
> And eventually I end up with a tarball mypackage_1.0.tar.gz.
>
> Stage 3. How to make the round trip? I add more R code, and
> re-generate a package.
>
> package.skeleton obliterates the help files I've already edited.
>
See ?dump and ?prompt.
> So keeping the R code in sync with the documentation appears to be a
hassle.
>
> In other languages, I've seen to write the documentation inside the
> code files and then post-process to make the documentation. ?Is there
> a similar thing for R, to unify the R code development and
> documentation/package-making process?
>
Yes.  See the roxygen / roxygen2 and devtools packages.
> pj
>
> --
> Paul E. Johnson
> Professor, Political Science
> 1541 Lilac Lane, Room 504
> University of Kansas
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
Best,
--
Joshua Ulrich  |  FOSS Trading: www.fosstrading.com

On 9 September 2011 at 11:38, Paul Johnson wrote:
| Hi,
| 
| I'm asking another one of those questions that would be obvious if I
| could watch your work while you do it.
| 
| I'm having trouble understanding the workflow of code and package
maintenance.
| 
| Stage 1.  Make some R functions in a folder.  This is in a Subversion repo
| 
| R/trunk/myproject
| 
| Stage 2. Make a package:
| 
| After the package.skeleton, and R check, I have a new folder with the
| project in it,
| 
| R/trunk/myproject/mypackage
|   DESCRIPTION
|   man
|   R
| 
| I to into the man folder and manually edit the Rd files. I don't
| change anything in the R folder because I think it is OK so far.
| 
| And eventually I end up with a tarball mypackage_1.0.tar.gz.
| 
| Stage 3. How to make the round trip? I add more R code, and
| re-generate a package.
| 
| package.skeleton obliterates the help files I've already edited.

In my case a lot of 'C-x f' to open a new man/foo.Rd file, maybe a new
src/foo.cpp file, maybe a new unit tests file ...  It all depends.  I tend
then call little one-line shell commands which may rebuild the package and
run test expressions via littler.

But as a general rule, code and documentation (still) gets written (manually)
in an editor.

| So keeping the R code in sync with the documentation appears to be a hassle.

But 'R CMD check' is vigilant and reminds you when you get some details
wrong.
 
| In other languages, I've seen to write the documentation inside the
| code files and then post-process to make the documentation.  Is there
| a similar thing for R, to unify the R code development and
| documentation/package-making process?

You can also follow the cool kids who these days tie some of this together
using roxygen.
 

And just as a philosophical note: There is (still) no silver bullet.  The
slow boring of thick boards applies not only to politics (as per Max Weber)
but quite conceivably to programming.

Hth, Dirk
 
| pj
| 
| -- 
| Paul E. Johnson
| Professor, Political Science
| 1541 Lilac Lane, Room 504
| University of Kansas
| 
| ______________________________________________
| R-devel at r-project.org mailing list
| https://stat.ethz.ch/mailman/listinfo/r-devel

-- 
Two new Rcpp master classes for R and C++ integration scheduled for 
New York (Sep 24) and San Francisco (Oct 8), more details are at
http://dirk.eddelbuettel.com/blog/2011/08/04#rcpp_classes_2011-09_and_2011-10
http://www.revolutionanalytics.com/products/training/public/rcpp-master-class.php

On 09/09/2011 12:38 PM, Paul Johnson wrote:
> Hi,
>
> I'm asking another one of those questions that would be obvious if I
> could watch your work while you do it.
>
> I'm having trouble understanding the workflow of code and package
maintenance.
>
> Stage 1.  Make some R functions in a folder.  This is in a Subversion repo
>
> R/trunk/myproject
>
> Stage 2. Make a package:
>
> After the package.skeleton, and R check, I have a new folder with the
> project in it,
>
> R/trunk/myproject/mypackage
>    DESCRIPTION
>    man
>    R
>
> I to into the man folder and manually edit the Rd files. I don't
> change anything in the R folder because I think it is OK so far.
>
> And eventually I end up with a tarball mypackage_1.0.tar.gz.
>
> Stage 3. How to make the round trip? I add more R code, and
> re-generate a package.
>
> package.skeleton obliterates the help files I've already edited.
You should only run it once.  After that, add your code by editing *.R 
files in the R directory, sourcing them, and generate *.Rd files using 
prompt().  As Dirk said, run R CMD check when you think you're done, and 
it will point out how wrong you are.
> So keeping the R code in sync with the documentation appears to be a
hassle.
If you write the *.Rd file before (like Spencer) or soon after writing 
the code, then design errors will usually stick out at you, and you can 
modify the functions.  If you keep your functions small, you'll get them 
working early, and won't have a lot of problems keeping them in sync 
with the docs, because they won't change much once you get them right.

Duncan Murdoch
> In other languages, I've seen to write the documentation inside the
> code files and then post-process to make the documentation.  Is there
> a similar thing for R, to unify the R code development and
> documentation/package-making process?
>
> pj
>

I create & maintain all my packages using the 'mvbutils' package.
Documentation in plain-text format (not Rd) is stored along with each function
definition--- so when you edit your function, its doco is right there too, and
it looks like proper documentation, not code-comments or quasi-Latex. The entire
package source tree, including the Rd files, is created automatically by the
'preinstall' function, after which you can then R-BUILD the package as
usual. However, with 'mvbutils' you only need R-BUILD when you want a
distribution version for others. Normal maintenance doesn't require R-BUILD;
you can add/remove/edit functions, documentation, and data to the package
on-the-fly while it is loaded, with no need to unload/uninstall/rebuild/reload.

It works with compiled code, too. My own way of working with compiled code is a
bit different to most other people's, but colleagues who use more
traditional routes have also successfully used 'mvbutils' to build and
maintain their packages.

In the spirit of several other replies-- I spent months developing this stuff
and getting it to run smoothly, precisely because I'm lazy and have a
limited memory...

HTH (though whether "yet another approach is..." will actually help
you, I'm not sure)

Mark


Mark Bravington
CSIRO CMIS
Marine Lab
Hobart
Australia
________________________________________
From: r-devel-bounces at r-project.org [r-devel-bounces at r-project.org] On
Behalf Of Paul Johnson [pauljohn32 at gmail.com]
Sent: 10 September 2011 02:38
To: r-devel at stat.math.ethz.ch
Subject: [Rd] Please explain your workflow from R code -> package -> R
code     -> package

Hi,

I'm asking another one of those questions that would be obvious if I
could watch your work while you do it.

I'm having trouble understanding the workflow of code and package
maintenance.

Stage 1.  Make some R functions in a folder.  This is in a Subversion repo

R/trunk/myproject

Stage 2. Make a package:

After the package.skeleton, and R check, I have a new folder with the
project in it,

R/trunk/myproject/mypackage
  DESCRIPTION
  man
  R

I to into the man folder and manually edit the Rd files. I don't
change anything in the R folder because I think it is OK so far.

And eventually I end up with a tarball mypackage_1.0.tar.gz.

Stage 3. How to make the round trip? I add more R code, and
re-generate a package.

package.skeleton obliterates the help files I've already edited.

So keeping the R code in sync with the documentation appears to be a hassle.

In other languages, I've seen to write the documentation inside the
code files and then post-process to make the documentation.  Is there
a similar thing for R, to unify the R code development and
documentation/package-making process?

pj

--
Paul E. Johnson
Professor, Political Science
1541 Lilac Lane, Room 504
University of Kansas

______________________________________________
R-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel