[Bioc-devel] Package reference manuals in html

Github allows you to set the branch for the docs directory if I recall.
Perhaps a separate branch with a docs directory (not master) is a viable
way to go?

Sean

On Dec 23, 2016, at 12:16 PM, Laurent Gatto <lg390 at cam.ac.uk> wrote:


There's actually another side-effect for Bioconductor. The package
website is (by default) generated in the package's ./docs
directory. This is very handy, as it can be set directly on Github as a
Github page and becomes available as https://username.github.io/pkgname.

This also means that the docs directory (which is about 5.5M for
MSnbase) ends up on hedgehog. It is easy for it not to be part of the
package build artefact using .Rbuildignore, but I am not sure how to
easily push it to github but not hedgehog when using git-svn.

Laurent

On 23 December 2016 16:36, Laurent Gatto wrote:

Dear all,

I'm following up re my online references suggestion with my recent
experience with Hadley's pkgdown package

 https://github.com/hadley/pkgdown

It doesn't address the cross-package issue (which is a difficult one
anyway), but does pretty much everything else (with some caveats though,
see below).

Here are 2 examples

- MSnbase: http://lgatto.github.io/MSnbase/
- hpar: http://lgatto.github.io/hpar/

It uses the REAMDE file as index page, creates html documents for all Rd
files in man, an article tab for vignettes (but see below) and a News
tab (but see below)

The biggest caveats is that only Rmd vignettes are taken into account;
Rnw are completely ignored (they don't show up at all in the Articles
tab). This is not going to be tackled by the developer [1].

[1] https://github.com/hadley/pkgdown/issues/220

I had a quick look at the code and patching pkgdown (and probably
rmarkdown) to build Rnw/pdf vignettes would take too much time I could
devote at the moment. I would be satisfied if the Rnw were not build but
at least there were links in the Articles tab pointing to the vignettes
Bioconductor landing pages. On the other hand, I am migrating to
BiocStyle's html_document2 with the nice floating table of contents...

Regarding the News tab, only NEWS.md (markdown format) are considered;
NEWS in Rd are ignored too.

Hope this helps.

Best wishes,

Laurent

On 16 March 2016 23:33, Andrzej Ole? wrote:

Hi all,

I had a discussion earlier today with Martin and Dan on providing
online man pages for Bioconductor packages. As we dived into
implementation details, it turned out that this idea is a little bit
more complex and resource-intensive than originally anticipated.

The main problem in generating man pages in a repository-wide fashion
seems to be the cross-linking of packages. Briefly, in order to
generate the links, apparently one needs to generate the html pages in
an R installation which is aware of the other packages. For example,
the Rd macro \linkS4class{ClassName} takes as argument only the class
name, and the corresponding package containing the class definition is
"automagically" resolved by R. I'm not sure how this could be done
manually, on a per-package basis. So by the end of the day, in order to
generate static man pages, we would need to maintain a complete BioC
repo installation, possibly on a system with the --enable-prebuilt-html
configure option. Unfortunately, it seems unfeasible to exploit the
build servers for this, as this would significantly increase the
computational burden. This is because currently only around 2/5 of all
software and data packages are actually being installed by the build
system. The rest which does not have any reverse dependencies is
skipped. Installing the remaining 3/5 of packages on a regular basis,
not to mention the heavy annotation packages, is a little bit of an
overkill. So piggy-backing on the existing infrastructure doesn't seem
realistic.

On top of this, even if we would have access to a machine with a
complete, up-to-date BioC installation (maybe by just updating the
packages after the repo gets rebuild rather than re-installing them
each time from scratch), it remains an open question how "external"
links to, let's say, CRAN packages, or even base R packages, should be
handled.

A lightweight and easy to implement alternative for those willing to
share self-hosted documentation of their packages, could be to provide
in the package DESCRIPTION file a "Documentation" field containing a
link to external resource, which would then appear on the package
landing page next to the vignettes and pdf manual. The obvious
downsides of this solution are: 1. no package cross-links, and 2. the
burden of keeping the documentation in sync with the package version on
BioC would be in maintainer's hands...

I will try to contact the authors of rdocumentation.org - maybe they
have some useful comments or even code which they would be willing to
share. In any case, it would be good to know what their experience is
and why did they stop maintaining their service. Maybe the BioC
community could jump in and help them to resolve the bottlenecks and
keep the website up to date.

Cheers,
Andrzej


On Tue, Mar 8, 2016 at 4:36 PM, Andrzej Ole? <andrzej.oles at gmail.com>
wrote:

   Hi Martin,

   thank you for your suggestions - I would be happy to contribute to
   this! I could help with developing the scripts for generating man
   pages, and integrating them with the website layout.

   As for rendering the man pages, I suggest that we try a similar
   approach to the one used by knitr::knit_rd() rather than plain
   tools::Rd2HTML(). It has the advantage that the examples are
   actually run, and the results, e.g. plots, are included in the
   output documents. I hope you can appreciate the added value by
   comparing the following man page rendered using tools::Rd2HTML()
   and knitr::knit_rd(), respectively.
   http://www.huber.embl.de/users/aoles/man/Image.html
   http://www.huber.embl.de/users/aoles/man/Image-knitr.html
   Regarding the additional dependencies: we kind of already rely on
   knitr when compiling vignettes, so this this shouldn't add much to
   the maintenance burden.

   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

--
Laurent Gatto | @lgatt0
http://cpu.sysbiol.cam.ac.uk/
http://lgatto.github.io/