[Bioc-devel] Package reference manuals in html

[Morgan, Martin]

One thing about accessing the html versions locally (e.g., via ? with options(help_type="html")] or help.start() or Rstudio) is that you get the version relevant to your R / Bioconductor, rather than whatever is at the top of google; I guess the same applies to the pdf versions, and the reason that there isn't more current confusion is because the online pdf versions are not as useful as the off-line help system.

I think Laurent was interested in an integration of help pages across packages (which is the appeal of rdocumentation.org?), not just rendering the help pages in html rather than pdf? An integration of help pages would definitely be a big job with substantial development and maintenance; we will not be undertaking this ourselves.

For the more limited case of adding a (directory of) html files for the the manual, it's not impossible that we could find the resources to do this in the next 6 months.

One intermediate and helpful step for those willing to help would be to develop the code to process help pages into a style consistent with the bioconductor web site. One place where this could be implemented would be the BiocStyle package (https://github.com/Bioconductor-mirror/BiocStyle but hmm, seems like there's a slightly out of sync version at https://github.com/Bioconductor/BiocStyle that would be more convenient...). Perhaps this really means only developing a css style sheet and R's tools::Rd2HTML() (I'm very reluctant to introduce dependencies into the build system, and am very conservative about inclusion of fancy features in the html -- these become significant maintenance burdens moving forward).

The web site is generated by https://github.com/Bioconductor/bioconductor.org, with the style sheet at https://github.com/Bioconductor/bioconductor.org/blob/master/assets/style/bioconductor.css. The package landing pages are templated using layouts/_bioc_views_package_detail.html. The idea would be to end up with layouts/_bioc_man_index.html and _bioc_man_body.html that wrapped output from BiocStyle in the overall bioc page.

The implementation suggestions above are just a sketch and could be quite misguided. If there's interest then probably we should set up a hangout to discuss in a little more detail.

Martin

________________________________________
From: Bioc-devel <bioc-devel-bounces at r-project.org> on behalf of Hartley, Stephen (NIH/NHGRI) [F] <stephen.hartley at nih.gov>
Sent: Wednesday, March 2, 2016 11:46 AM
To: Laurent Gatto; bioc-devel
Subject: Re: [Bioc-devel] Package reference manuals in html

I'd like to second this. Currently Bioconductor hosts the pdf reference manuals, but those are often sub-ideal. The page breaks make it harder to read, the fixed width basically makes it either too small or too big depending on your display, you can't navigate cross-package links, and in general using paper-formatted software documentation is just poor form.

Yihui, the creator of knitr, has a blog post where he shows how to do this. There are a lot of ways to do this, and it's generally pretty straightforward.
http://yihui.name/en/2012/10/build-static-html-help/

You can also use a function in knitr, knit_rd(), which builds the examples as well and inserts the output right onto the page. That's what I used to make the docs for QoRTs (http://hartleys.github.io/QoRTs/Rhtml/index.html) and JunctionSeq (http://hartleys.github.io/JunctionSeq/Rhtml/index.html).

Or you can use the staticdocs package, which does the same basic thing but prettier (see ggplot2's docs: http://docs.ggplot2.org/current/)

The nuclear option, of course, is to do what CRAN does and rebuild R on (one of) the servers using the --enable-prebuilt-html configure option. That might affect other things, though, and might not be ideal.

Does any of this seem like a viable option for Bioconductor? I think it could be an incredibly valuable resource for the community. Are there any technical issues that haven't been considered in the above?

Regards,
Steve Hartley

-----Original Message-----
From: Laurent Gatto [mailto:lg390 at cam.ac.uk]
Sent: Tuesday, March 01, 2016 6:42 AM
To: bioc-devel
Subject: [Bioc-devel] Package reference manuals in html


Dear all,

I find the http://www.rdocumentation.org/ site very useful to refer to nicely formatted online man pages individually. Unfortunately, this resource is terribly outdated and not maintained anymore.

I was wondering if Bioconductor had any interest in serving an html version of individual reference manuals in addition to the pdf that are already available on the package landing pages.

Is there anything I or any other members of the community could help with to get this up and running?

Best wishes,

Laurent

_______________________________________________
Bioc-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel

_______________________________________________
Bioc-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel


This email message may contain legally privileged and/or confidential information.  If you are not the intended recipient(s), or the employee or agent responsible for the delivery of this message to the intended recipient(s), you are hereby notified that any disclosure, copying, distribution, or use of this email message is prohibited.  If you have received this message in error, please notify the sender immediately by e-mail and delete this email message from your computer. Thank you.