search

aiorazabala / qmethod

R package to analyse Q methodology data
GNU General Public License v2.0
34 stars 18 forks source link

migrate documentation to roxgen2 #31

Closed maxheld83 closed 7 years ago

maxheld83 commented 9 years ago

I'm currently writing the document for my import.qsorts (etc.) functions, and it's a bit of a pain.

I'm wondering whether it makes sense to migrate to roxygen2, which allows literate programming-style inline documentation, and then writes *.Rds based on that documentation. Also automates NAMESPACE shenanigans and some of DESCRIPTION.

Or maybe this is just another package / source of problems to worry about for a relatively minor, if menial task?

maxheld83 commented 9 years ago

incidentally, there is a package that automates migration from *.Rd-based docs to Roxygen2 (the reverse of the above, kinda): http://yihui.name/Rd2roxygen/ Gotta love the R Community.

aiorazabala commented 9 years ago

I don't know how roxygen works. The current system is fine by me (simple enough), but if you believe that roxygen to be worth it (if the project will be large enough, etc.), then you're welcome to migrate to it.

To do the Rd documentation manually, you just need to copy another Rd file and change the filename and content accordingly. Then adding the new functions to NAMESPACE is easy, just include the name of the new function within the export("...") vector. No need to change DESCRIPTION unless you are adding a new dependency package.

Next, you need to rebuild (and test) the package in order for the function to be recognised. In a Terminal in linux (or something equivalent in a command line in Win/Mac): R CMD build qmethod R CMD check --as-cran qmethod_x.tar.gz R CMD INSTALL qmethod_x.tar.gz

maxheld83 commented 9 years ago

thanks @aiorazabala Agreed – seems to be overkill for now, will put this on the backlog. Will run the tests as suggested.

maxheld83 commented 9 years ago

uh, the documentation is killing me. Seems like there are lot of things that computers might be better at.. Might look into this (roxygen) sooner, rather than later, to make this easier. Have to check whether there is a way to retain the old, manually documented *.Rds, without changing any of that.

maxheld83 commented 8 years ago

This is just one function so far, and I won't change all the other docs anytime soon. Also, roxygen does not yet create the NAMESPACE, because for that we need to migrate completely

maxheld83 commented 7 years ago

done in pensieve, probably not necessary otherwise here. https://github.com/QWrks/pensieve/issues/117