search

thibautjombart / adegenet

adegenet: a R package for the multivariate analysis of genetic markers
166 stars 64 forks source link

porting documentation to roxygen2 #4

Closed romunov closed 9 years ago

romunov commented 9 years ago

I was thinking of porting the documentation to roxygen2. Would something like this be within the project goals?

thibautjombart commented 9 years ago

Definitely. I just started using it for other projects a couple of weeks ago. For a project the size of adegenet, we would need some way of generating the roxygen2 from the Rds. I wouldn't be surprised if it existed, but haven't looked into it yet - working on other packages at the moment. Insight welcome.

On Wed, Feb 25, 2015 at 1:10 PM, Roman Luštrik notifications@github.com wrote:

I was thinking of porting the documentation to roxygen2. Would something like this be within the project goals?

— Reply to this email directly or view it on GitHub https://github.com/thibautjombart/adegenet/issues/4.

thibautjombart commented 9 years ago

ps: Roman, wanna join the development team? ;)

On Wed, Feb 25, 2015 at 1:54 PM, Thibaut Jombart thibautjombart@gmail.com wrote:

Definitely. I just started using it for other projects a couple of weeks ago. For a project the size of adegenet, we would need some way of generating the roxygen2 from the Rds. I wouldn't be surprised if it existed, but haven't looked into it yet - working on other packages at the moment. Insight welcome.

On Wed, Feb 25, 2015 at 1:10 PM, Roman Luštrik notifications@github.com wrote:

I was thinking of porting the documentation to roxygen2. Would something like this be within the project goals?

— Reply to this email directly or view it on GitHub https://github.com/thibautjombart/adegenet/issues/4.

romunov commented 9 years ago

It would appear Yihui has encountered a similar problem - and solved it for us. Enter Rd2roxygen. I'll give this a go and report back.

I would be glad to help out.

thibautjombart commented 9 years ago

Sounds cool. Welcome on board! I'm reorganising the folder and then will give you access. Best doing that stuff on a separate branch and merge back once it passes the checks. Cheers Thibaut

On Wed, Feb 25, 2015 at 1:57 PM, Roman Luštrik notifications@github.com wrote:

It would appear Yihui has encountered a similar problem - and solved it for us. Enter Rd2roxygen http://yihui.name/Rd2roxygen/. I'll give this a go and report back.

I would be glad to help out.

— Reply to this email directly or view it on GitHub https://github.com/thibautjombart/adegenet/issues/4#issuecomment-75963197 .

romunov commented 9 years ago

I'll make a pull request and once check the translation succeeded and clears checks, I'll suggest a merge.

thibautjombart commented 9 years ago

You're in. Just reorganised the folder, so if you pull now you should start from a cleanish version. Not quite ready to go on CRAN, but functional.

thibautjombart commented 9 years ago

Automated port seems to work pretty well, but the package does not install - a R file needs to be added in DESCRIPTION in the collate field:

> library(devtools)
> install()
Installing adegenet
'/usr/local/lib/R/bin/R' --vanilla CMD INSTALL  \
  '/home/thibaut/dev/adegenet/github'  \
  --library='/usr/local/lib/R/site-library' --install-tests 

* installing *source* package ‘adegenet’ ...
** libs
make: Nothing to be done for `all'.
installing to /usr/local/lib/R/site-library/adegenet/libs
** R
Error in .install_package_code_files(".", instdir) : 
files in '/home/thibaut/dev/adegenet/github/R' missing from 'Collate' field:
  adegenet-package.R
ERROR: unable to collate and parse R files for package ‘adegenet’
* removing ‘/usr/local/lib/R/site-library/adegenet’
* restoring previous ‘/usr/local/lib/R/site-library/adegenet’
Error: Command failed (1)
thibautjombart commented 9 years ago

The @@ trick seems to be the way to go - using it on other projects too.

thibautjombart commented 9 years ago

Otherwise, all good regarding the new branch you created. I'm new to github, I just realised forking might have been easier for you. But all done and working, so all good.

zkamvar commented 9 years ago

This is great!

Of course, nothing is perfect, and roxygen missed a few things. These are all the R files that Roxygen missed and I think they might have to be done by parse_and_save()? 

14:55:26~/Documents/adegenet (roxygen2)> grep -L "#'" R/*.R
R/PCtest.R
R/SNPbin.R
R/auxil.R
R/basicMethods.R
R/classes.R
R/export.R
R/fstat.R
R/glHandle.R
R/haploPop.R
R/inbreeding.R
R/old2new.R
R/propTyped.R
R/scale.R
R/sequences.R
R/servers.R
R/setAs.R
R/simOutbreak.R
R/snpposi.R
R/xvalDapc.R
R/zzz.R

Most of these are fixable, but I know from personal experience that S4 methods can be messy to deal with.

There are also the issues of the imported functions and DynLib. I can work on getting the imported functions and the DynLib in the NAMESPACE, if that's okay with you, @romunov.

For now, here's a task list of what still needs to be done before the branch can work.

romunov commented 9 years ago

Works for me. I first started working on the low hanging fruit and I'll be doing harder and harder things. My next step will probably be your first check box, documenting undocumented functions. I can do some, but I will need some help for 'exotic' ones.

thibautjombart commented 9 years ago

Roger that. If you can point a finger at the exotic one, I'll sort them out. Cheers! =D

On Thu, Mar 5, 2015 at 7:12 AM, Roman Luštrik notifications@github.com wrote:

Works for me. I first started working on the low hanging fruit and I'll be doing harder and harder things. My next step will probably be your first check box, documenting undocumented functions. I can do some, but I will need some help for 'exotic' ones.

— Reply to this email directly or view it on GitHub https://github.com/thibautjombart/adegenet/issues/4#issuecomment-77317524 .

zkamvar commented 9 years ago

Most of the roadblocks I found for S4 documentation was in documenting new generic methods. This SO answer gives a nice example of how to properly document them using roxygen2: http://stackoverflow.com/questions/7356120/how-to-properly-document-s4-methods-using-roxygen2/7423698#7423698

thibautjombart commented 9 years ago

So, I have dispatched the bits of doc to their respective files. Not always pretty but should do the trick for now. Problem: I get the following error:

> document()
Updating adegenet documentation
Loading adegenet
Adding files missing in collate: adegenet-doctoclean.R, adegenet-package.R, datasets.R, packageImports.R
Creating a generic function for ‘plot’ from package ‘graphics’ in package ‘adegenet’
   ==========================
    adegenet 1.4-3 is loaded
   ==========================

 - to start, type '?adegenet'
 - to browse adegenet website, type 'adegenetWeb()'
 - to post questions/comments: adegenet-forum@lists.r-forge.r-project.org

Writing NAMESPACE
Error: Failure in roxygen block beginning SNPbin.R:1239
Missing name
In addition: There were 12 warnings (use warnings() to see them)
> warnings()
Warning messages:
1: In grepl("\n", lines, fixed = TRUE) :
  input string 388 is invalid in this locale
2: In grepl("\n", lines, fixed = TRUE) :
  input string 998 is invalid in this locale
3: In grepl("\n", lines, fixed = TRUE) :
  input string 999 is invalid in this locale
4: In grepl("\n", lines, fixed = TRUE) :
  input string 1000 is invalid in this locale
5: In grepl("\n", lines, fixed = TRUE) :
  input string 388 is invalid in this locale
6: In grepl("\n", lines, fixed = TRUE) :
  input string 998 is invalid in this locale
7: In grepl("\n", lines, fixed = TRUE) :
  input string 999 is invalid in this locale
8: In grepl("\n", lines, fixed = TRUE) :
  input string 1000 is invalid in this locale
9: In grepl("\\s*#+' ?", c(" # end df2genind", "", "", "",  ... :
  input string 45 is invalid in this locale
10: In grepl("\\s*#+' ?", c("", "", "", "", "", "#' Importing data from several softwares to a genind object",  ... :
  input string 48 is invalid in this locale
11: In grepl("\\s*#+' ?", c("", "", "", "", "", "#' Importing data from several softwares to a genind object",  ... :
  input string 49 is invalid in this locale
12: In grepl("\\s*#+' ?", c("", "", "", "", "", "#' Importing data from several softwares to a genind object",  ... :
  input string 50 is invalid in this locale
thibautjombart commented 9 years ago

Help welcome!

zkamvar commented 9 years ago

I'll see if I can get it.

zkamvar commented 9 years ago 
> devtools::document(roclets=c('rd', 'collate', 'namespace'))

Updating adegenet documentation
Loading adegenet
Adding files missing in collate: adegenet-doctoclean.R, adegenet-package.R, datasets.R, packageImports.R
Creating a generic function for ‘plot’ from package ‘graphics’ in package ‘adegenet’
Writing HWE.test.genind.Rd
Writing SNPbin-class.Rd
Writing genlight-class.Rd
Skipping invalid path:  .bin2raw.Rd 
Skipping invalid path:  coerce-methods
#'.Rd 
Writing coerce-methods.Rd
Writing adegenet-package.Rd
Writing Auxiliary-functions.Rd
Writing Website-and-tutorials.Rd
Writing virtualClasses.Rd
Writing genind-class.Rd
Writing popInfo-class.Rd
Writing as-methods-in-adegenet.Rd
Writing scatter.dapc.Rd
Writing a.score.Rd
Writing genind2genotype.Rd
Writing glSum.Rd
Writing na.replace-methods.Rd
Writing isPoly-methods.Rd
Writing import2genind.Rd
Writing findMutations.Rd
Writing pairDistPlot.Rd
Writing propTyped-methods.Rd
Writing scaleGen-methods.Rd
Writing DNAbin2genind.Rd
Writing adegenetServer.Rd
Writing snpposi.test.Rd
Writing global.rtest.Rd
There were 50 or more warnings (use warnings() to see the first 50)
Documentation completed
zkamvar commented 9 years ago

There are going to be a lot of rough edges, but at least most of the documentation is represented.

thibautjombart commented 9 years ago

I've looked into it more.. problem is a lot of functions are documented in the same file, some of them really tiny accessors. @describeIn will help regenerate the doc but for now it looks like a more feasible approach is using hybrid documentation, so that new stuff can be roxygen2 but old stuff stays the way it is for now.

I'm testing that on the master for now and it looks like I have it working. Regenerating the right namespace was the issue.

On Mon, Mar 16, 2015 at 11:03 PM, Zhian N. Kamvar notifications@github.com wrote:

There are going to be a lot of rough edges, but at least most of the documentation is represented.

— Reply to this email directly or view it on GitHub https://github.com/thibautjombart/adegenet/issues/4#issuecomment-82064474 .

thibautjombart commented 9 years ago

Okay, stuff clearing up now. As of e75f28035b0, we have a working version with hybrid doc. New doc can be left as it was, new doc will be roxygen2. Example for doc already using roxygen2 are: chooseCN.R adegenet.package.R datasets.R

Some of the other files (mostly standalone functions) would be straightforward to port, but these won't be an emergency. Package is OP for new development. Switching to version 1.5-0 in view of the big changes to come. Oh yeah.

zkamvar commented 9 years ago

Should be noted that this version works when loading the namespace, but cannot currently be built. There are still some functions that are not exported from the namespace (e.g. inbreeding), and those will need explicit export statements in their roxygen blocks.

romunov commented 9 years ago

Hybrid documentation sounds like the optimal solution right now.