[Bioc-devel] Package reference manuals in html

Andrzej Oleś andrzej.oles at gmail.com
Fri Mar 4 14:45:54 CET 2016


Hi,
this is just to clarify the relation between the two github repos
https://github.com/Bioconductor-mirror/BiocStyle and
https://github.com/Bioconductor/BiocStyle mentioned by Martin: actually,
these two are perfectly in sync right now. The "This branch is 3 commits
ahead, 3 commits behind Bioconductor-mirror:master." message is just
an inevitable(?)
artifact of using the bioc git mirrors approach (
https://www.bioconductor.org/developers/how-to/git-mirrors/).
Bioconductor-mirror/BiocStyle is a read-only mirror automatically
synchronized with the bioc svn, whereas its fork Bioconductor/BiocStyle is
the proper place to which pull requests and issues should be submitted, and
where any development should happen.

Cheers,
Andrzej

On Fri, Mar 4, 2016 at 2:20 PM, Morgan, Martin <
Martin.Morgan at roswellpark.org> wrote:

> 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.
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>

	[[alternative HTML version deleted]]



More information about the Bioc-devel mailing list