search

mlr-archive / mlr-tutorial

The mlr package online tutorial
http://mlr-org.github.io/mlr/
20 stars 11 forks source link

rdocumentation still on 2.2 #30

Closed schiffner closed 8 years ago

schiffner commented 8 years ago

We talked about this briefly some time ago in this mega thread. The docs of mlr on rdocumentation are still for version 2.2. Meanwhile, many help pages are outdated and there are whole tutorial pages with the majority of links broken (like visualization or benchmark experiments).

I personally find this annoying. On the other hand, nobody has complained yet.

Does anyone know of an alternative platform? I checked but couldn't find anything (inside-R for example is on mlr version 1.something).

We could generate the docs ourselves. Possibilities are:

zmjones commented 8 years ago

Looks like this might work.

berndbischl commented 8 years ago

this is really annoying as rendering to html should be really easy. i tried staticdocs before and we once had html online help pages for mlr that worked. but what you are saying does not sound very reassuring.

berndbischl commented 8 years ago

@zmjones Nice find. So it would be an easy URL change to use this? And we just pray that they dont dissapear like rdocumentation.org?

schiffner commented 8 years ago

@zmjones: Thanks, hadn't found this.

mllg commented 8 years ago

There is also https://github.com/hadley/staticdocs and http://www.inside-r.org/packages/.

Inside-R might be sufficient if we can keep up a frequent release cycle, otherwise we should provide additional documentation via staticdocs for the development version.

berndbischl commented 8 years ago

@mllg Julia already said staticdocs did not work for her (with mlr)?

And we also looked at inside-r before. And if we need staticdocs on top of it it also isnt a (reliable?) option?

berndbischl commented 8 years ago

Just to be clear, I would love staticdocs to work. But I am really annoyed at this, twofold. a) We invested lots of work into this already b) It still sucks.

berndbischl commented 8 years ago

or better b) = we kinda need this for the tutorial, and all the links are broken, which is why it sucks.

schiffner commented 8 years ago

So I checked out Zach's find. It looks like they have everything but the mandatory packages like base, stats, etc.

Thanks Michel. I could swear that last week mlr on inside-r was on version 1.18 or something like this...

How much work did you invest in staticdocs already? Did it work? My only problem with staticdocs and mlr were errors caused by some of the /cr. I tried it with some of my own packages and that went well.

mllg commented 8 years ago

I'll push some doc fixes in a few minutes.

mllg commented 8 years ago

With these fixes you should be able to compile most pages to html with build_site(), I still had trouble with the index though.

https://github.com/mlr-org/mlr/pull/583

schiffner commented 8 years ago

@mllg: Thank you very much.

Where do you think should I put the html docs? mlr, mlr-tutorial, own repo?

mllg commented 8 years ago

IMHO a repository "mlr-help" would be neat.

berndbischl commented 8 years ago

Where do you think should I put the html docs? mlr, mlr-tutorial, own repo?

We are going to create them once per CRAN release, arent we? I might vote for extra repo.

mllg commented 8 years ago

Has anyone tried knitr yet? http://yihui.name/en/2012/10/build-static-html-help/

mllg commented 8 years ago

Well, I think knitr cannot handle external links until you compile all installed packages... Forget about it.

schiffner commented 8 years ago

Only for like 5 mins. I had the same problem and didn't look further.

schiffner commented 8 years ago

Only for completeness: (As inside-r) http://www.crantastic.org/packages/mlr is also up to date now and also has docs for older mlr versions.

schiffner commented 8 years ago

Forget what I said about crantastic. They don't have docs.

Both inside-r and http://rpackages.ianhowson.com have mlr 2.7 docs

inside-r:

http://rpackages.ianhowson.com

I pushed a tutorial version where I link to http://rpackages.ianhowson.com for contributed and recommended packages and inside-r for base packages (inside-r seems more up-to-date for these packages than rdocumentation) and changed everything such that we can easily switch between platforms (or our own docs if we generate them ourselves).

c8f28b0a07c07b9d4aa846b13eaad9323ecaeb23

berndbischl commented 8 years ago

does not have docs for base packages

who cares.

up to date as far as I checked

sounds good! I guess this is most relevant.

berndbischl commented 8 years ago

hmm, ok so i see you also dont need my comments as you are already finishing a good compromise? hopefully it is not too much work

schiffner commented 8 years ago

It was a bit of work, that's why I procrastinated this long... You can look at the devel-version of the tutorial and see if you like.

berndbischl commented 8 years ago

I looked at it quickly but it is just more working links, to the ianhowson page now? So I guess there is nothing to dislike? Or check?

schiffner commented 8 years ago

Yep. Not much to see or check. Just wanted to keep you all informed and give you the opportunity for any kind of protest/suggestions. :)

berndbischl commented 8 years ago

closing this, as the ianhowson page seems to work

schiffner commented 8 years ago

At the moment we are back to rdocumentation because it's working now again and because inside-r is down... In the pretty frequent case that we introduce new functions we still might want to build our own documentation, but it's better to open a new clean issue for this.

berndbischl commented 8 years ago

At the moment we are back to rdocumentation because it's working now again and because inside-r is down... In the pretty frequent case that we introduce new functions we still might want to build our own documentation, but it's better to open a new clean issue for this.

why dont we use ianhowson? this shows mlr 2.9, while rdocumentation is again outdated at 2.8?

schiffner commented 8 years ago

Because the level version of the tutorial has dead links then.

berndbischl commented 8 years ago

Because the level version of the tutorial has dead links then.

? i dont get that

schiffner commented 8 years ago

Sorry, I meant "devel version".

What I mean is that we have quite often mismatches between the online docs (like rdocumentation) and the devel version of the tutorial, for example

It's not high-prio though.

berndbischl commented 8 years ago

well my 2 cents on this:

1) all of what you list i think we have to / should simply live with. it is the devel version of the tutorial for a reason. also: if we have faster release cycles, that problem will be much less severe.

2) it sounds that this has nothing to do with rdocumentation vs. ianhowson. so again: why do we use a service which is continously outdated instead one which seemed to have been automatic uptodate in the past each time i checked?

schiffner commented 8 years ago

1) all of what you list i think we have to / should simply live with. it is the devel version of the tutorial for a reason. also: if we have faster release cycles, that problem will be much less severe.

Ok.

2) it sounds that this has nothing to do with rdocumentation vs. ianhowson.

I never said that.

so again: why do we use a service which is continously outdated instead one which seemed to have been automatic uptodate in the past each time i checked?

  • ianhowson does not have all packages.
  • rdocumentation is up-to-date, very, very much improved and has nice things like for example has hyperlinks between doc pages, a console where you can directly run the examples etc.
berndbischl commented 8 years ago

rdocumentation is up-to-date, very, very much improved and has nice things like for example has hyperlinks between doc pages, a console where you can directly run the examples etc.

thx for the clarification ;-) i will trust your (much more informed) judgement here. close now?

schiffner commented 8 years ago

:) We can easily switch back and forth in case that rdocumentation causes problems again.