[ESS] ESS, devtools, and documentation

Martin Maechler maechler at stat.math.ethz.ch
Sat Oct 18 10:30:58 CEST 2014


it was almost fine,  ... and I think it is more flexible to keep the
"global"  .ess.helpFUN

For you, Timothy, or any other working with released ESS, a nicer
workaround should be to
do -- once in your session -- so you could do it on the same line in
your R scripts where you have  require(devtools)
{or library(..) if you really prefer} :

   .ess.helpFUN <- get("help", globalenv())

With my modification, his will continue to work in future ESS versions.
However: Vitalie's (and mine) fix does not solve the problem
completely:  After all devtools wants to get the help page from the
package source without attaching the package to the search() path.
So, the above workaround does ensure regular help works for all
packages you have in search(), it will *not* find the help pages of
the "load_all(.) -- pseudo attached package".
Only if you additionally attach (a typically older version of) your
package {using  require() or library()},
 you will get the (old version of) help pages for that package.
OTOH: if you use devtools for working with your package and if you use
ESS,  you rather open the *.Rd files of your source package and use
C-c C-p to preview the help all in the ESS way.

Note: We  (ESS maintainers) took all the care to *not* redefine basic
R functions but use our wrappers ..


On Sat, Oct 18, 2014 at 12:15 AM, Vitalie Spinu <spinuvit at gmail.com> wrote:
>
>
> Ok, I can reproduce. Devtools is getting "smarter" and "smarter". Now
> there is a whole new environment devtools_shims that holds "?", "help"
> and "system.file".
>
>    getAnywhere(help)
>    2 differing objects matching ‘help’ were found
>    in the following places
>      devtools_shims
>      package:utils
>      namespace:utils
>
>
> ESS uses "help" from utils package. I can easily fix that by getting
> "help" function from globalenv to play along with ingenious packages
> like that.
>
>
> ESSR's .basic.R is very sensitive to changes as it must be compatible
> all the way back to R 1.1 :) Martin, could you please look at
>
>   https://github.com/emacs-ess/ESS/commit/76fd568efe3055d0884fda2bf9046d2e248c19ed
>
> and check if it's fine.
>
>
>   Vitalie
>
>
>  >>> "Timothy W. Hilton" on Fri, 17 Oct 2014 11:51:14 -0700 wrote:
>
>  > Hi Vitalie,
>  > print(help("Park_Falls")) successfully displays the help text in the R
>  > session window.  This helps a lot; thanks for the suggestion.  Now I can
>  > access my docs to refresh my memory how I meant for things to work when
>  > I was last working on the package.
>
>  > As for a reproducible example, I'm happy to send you my package if you
>  > like.  I did an experiment this morning, though, and the same thing
>  > happens if I download the source for ggplot2
>  > (http://cran.cnr.berkeley.edu/src/contrib/ggplot2_1.0.0.tar.gz), extract
>  > the tarball, load it using devtools, and try to access its documentation
>  > within ESS.
>
>  > in a new R session:
>  > library(devtools)
>  > load_all('/Users/tim/Software/ggplot2')
>
>  > Now choosing at random the 'coord_trans' function, all three of
>
>  > ?coord_trans
>  > help(coord_trans)
>  > C-c C-v coord_trans
>
>  > produce "No documentation for ‘coord_trans’ in specified packages and
>  > libraries:" in the minibuffer.
>
>  > print(help(coord_trans))
>
>  > displays the help in the R command window buffer, as expected.
>
>  > Thanks for looking into this, and as always, thanks for your work on
>  > ESS!
>
>  > best,
>  > Tim
>
>  > On Thu, Oct 2014, 16 at 06:38:07PM -0700, Vitalie Spinu wrote:
>  >>
>  >> Strange. Would be nice to have a reproducible example.
>  >>
>  >> From ESS, what do you see when you do
>  >>
>  >> print(help("Park_Falls"))
>  >>
>  >> Vitalie
>  >>
>  >> >>> "Timothy W. Hilton" on Thu, 16 Oct 2014 09:50:44 -0700 wrote:
>  >>
>  >> > Hi Vitalie,
>  >> > Thanks for your quick response!  I meant that it works when I start R
>  >> > within my terminal (iTerm2 on my mac), but I just checked and it also
>  >> > does work when I start R within emacs shell prompt (aka M-x shell)
>  >> > (transcript below).
>  >>
>  >> > Thanks,
>  >> > Tim
>  >>
>  >> > ==================================================
>  >> > tim at ucmerced007-206 ~/work/Code/VPRM
>  >> >   % R
>  >> > R
>  >> > ]2;R ]1;R
>  >> > R version 3.1.1 (2014-07-10) -- "Sock it to Me"
>  >> > Copyright (C) 2014 The R Foundation for Statistical Computing
>  >> > Platform: x86_64-apple-darwin13.1.0 (64-bit)
>  >>
>  >> > R is free software and comes with ABSOLUTELY NO WARRANTY.
>  >> > You are welcome to redistribute it under certain conditions.
>  >> > Type 'license()' or 'licence()' for distribution details.
>  >>
>  >> >   Natural language support but running in an English locale
>  >>
>  >> > R is a collaborative project with many contributors.
>  >> > Type 'contributors()' for more information and
>  >> > 'citation()' on how to cite R or R packages in publications.
>  >>
>  >> > Type 'demo()' for some demos, 'help()' for on-line help, or
>  >> > 'help.start()' for an HTML browser interface to help.
>  >> > Type 'q()' to quit R.
>  >>
>  >> >> library(devtools)
>  >> > library(devtools)
>  >> >> load_all('VPRM_Rpkg')
>  >> > load_all('VPRM_Rpkg')
>  >> > Loading VPRMLandSfcModel
>  >> >> ?Park_Falls
>  >> > ?Park_Falls
>  >> > WARNING: terminal is not fully functional
>  >> > -  (press RETURN)
>  >> > Park_Falls              package:VPRM_Rpkg              R Documentation
>  >>
>  >> > Park Falls, Wisconsin, USA eddy covariance data and MODIS data
>  >>
>  >> > Description:
>  >>
>  >> >      The dataset Park_Falls contains MODIS observations as well as
>  >> >      ground-based eddy covariance flux tower data for the Ameriflux
>  >> >      tall tower located in Park Falls, Wisconsin, USA.  The data span
>  >> >      the period 1 May 2005 through 31 July 2005.
>  >>
>  >> > etc., etc.
>  >> > ==================================================
>  >>
>  >> > On Thu, Oct 2014, 16 at 09:46:29AM -0700, Vitalie Spinu wrote:
>  >> >>
>  >> >> There should be no difference.
>  >> >>
>  >> >> Do you mean that it works in emacs shell prompt (aka M-x shell)?
>  >> >>
>  >> >> Vitalie
>  >> >>
>  >> >> >>> "Timothy W. Hilton" on Thu, 16 Oct 2014 09:25:41 -0700 wrote:
>  >> >>
>  >> >> > Hi,
>  >> >> > I'm unable to access documentation for an R package I'm developing while
>  >> >> > using devtools within ESS.  Starting R within ESS and attempting to
>  >> >> > access some docs that I wrote:
>  >> >>
>  >> >> > M-x R
>  >> >> >> library(devtools)
>  >> >> >> load_all('VPRM_Rpckg')
>  >> >> >> ?Park_Falls
>  >> >>
>  >> >> > A message then appears in the minibuffer:
>  >> >> > No documentation for ‘Park_Falls’ in specified packages and libraries:
>  >> >>
>  >> >> > If I start R from the shell prompt the above sequence displays the
>  >> >> > documentation for Park_Falls, as expected.
>  >> >>
>  >> >> > ess-version: 14.09 [svn: 6041 (2014-09-13)] (loaded from /Users/tim/.emacs.d/ess-14.09/)
>  >> >> > GNU Emacs 24.3.1 (x86_64-apple-darwin13.4.0, NS apple-appkit-1265.21) of
>  >> >> > 2014-10-08 on Timothys-MacBook-Air.local
>  >> >>
>  >> >> > Any advice much appreciated!  I really love coding in ESS but accessing
>  >> >> > my own documentation is pretty important to me as I try to finalize this
>  >> >> > package I'm working on.
>  >> >>
>  >> >> > As always, thanks for making the excellent ESS available to the
>  >> >> > community!
>  >> >>
>  >> >> > best,
>  >> >> > Tim
>  >> >>
>  >> >> > --
>  >> >>
>  >> >> > Timothy W. Hilton
>  >> >> > Assistant Project Scientist
>  >> >> > School of Engineering
>  >> >> > University of California, Merced
>  >> >> > thilton at ucmerced.edu
>  >> >>
>  >> >> > ______________________________________________
>  >> >> > ESS-help at r-project.org mailing list
>  >> >> > https://stat.ethz.ch/mailman/listinfo/ess-help
>
> ______________________________________________
> ESS-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/ess-help



More information about the ESS-help mailing list