[Bioc-devel] Package reference manuals in html

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

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/

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/

Yes, this seems like a time where using a non-standard site directory on
Github is useful, or as Sean said, using a separate branch to serve the
html content.

-Robert

On Fri, Dec 23, 2016 at 12:19 PM Sean Davis <seandavi at gmail.com> wrote:

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

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

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

        [[alternative HTML version deleted]]

Yes, this seems like a time where using a non-standard site directory
on Github is useful, or as Sean said, using a separate branch to serve
the html content.

-Robert

On Fri, Dec 23, 2016 at 12:19 PM Sean Davis <seandavi at gmail.com> wrote:

    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
    >>>
    >>>    ________________________________________
    >>>    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

    >
    >
    > --
    > Laurent Gatto | @lgatt0
    > http://cpu.sysbiol.cam.ac.uk/
    > http://lgatto.github.io/
    >
    > _______________________________________________
    > Bioc-devel at r-project.org mailing list
    > https://stat.ethz.ch/mailman/listinfo/bioc-devel

Seems to be a good start.

But I don't understand why NEWS.md is ok and NEWS.Rd is ignored, given
than NEWS.md is not (I think) compatible and NEWS.Rd is.

Best,
Kasper

On Fri, Dec 23, 2016 at 12:24 PM, Robert M. Flight <rflight79 at gmail.com

wrote:

    Yes, this seems like a time where using a non-standard site
    directory on
    Github is useful, or as Sean said, using a separate branch to serve
    the
    html content.

    -Robert

    On Fri, Dec 23, 2016 at 12:19 PM Sean Davis <seandavi at gmail.com>
    wrote:

    > 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
    > >>>
    > >>>    ________________________________________
    > >>>    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

    > >
    > >
    > > --
    > > Laurent Gatto | @lgatt0
    > > http://cpu.sysbiol.cam.ac.uk/
    > > http://lgatto.github.io/
    > >
    > > _______________________________________________
    > > 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

        [[alternative HTML version deleted]]

Dear Sean and Robert,

On 23 December 2016 17:24, Robert M. Flight wrote:

Yes, this seems like a time where using a non-standard site directory
on Github is useful, or as Sean said, using a separate branch to serve
the html content.

It's not clear to me how a separate branch is the solution. In git-svn,
devel, release_3_4, ... are just that, different branches. How would you
set a gh-pages branch that contains a single dir so that it doesn't
conflict with master?

If I could set branch-specific directives in my .gitignore file, then I
would set this up for the Bioc branches. This seems to suggest it is
possible, but I haven't tried yet


http://stackoverflow.com/questions/1836742/using-git-how-do-i-ignore-a-file-in-one-branch-but-have-it-committed-in-another

Would it be possible to set something on the svn side to ignore/delete
the docs dir automatically, independently of what git does?

Laurent

-Robert

On Fri, Dec 23, 2016 at 12:19 PM Sean Davis <seandavi at gmail.com> wrote:

    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
    >>>
    >>>    ________________________________________
    >>>    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

    >
    >
    > --
    > Laurent Gatto | @lgatt0
    > http://cpu.sysbiol.cam.ac.uk/
    > http://lgatto.github.io/
    >
    > _______________________________________________
    > Bioc-devel at r-project.org mailing list
    > https://stat.ethz.ch/mailman/listinfo/bioc-devel

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

They are "orphan" branches, so they don't follow the parent. This was
the original protocol for creating project pages on github for the
longest time, you can see an example in the documentation here:https:/
/help.github.com/articles/creating-project-pages-using-the-command-line
/

They are a pain in the butt to work with, for sure. When I've done
deploying vignettes from travis, my solution was to create a separate
repo entirely, and then push from the master to gh-pages, as shown in
this shell script:https://github.com/rmflight/categoryCompare/blob/
master/.push_gh_pages.sh

I'm sure the same could be done using pkgdown.

If you don't like the idea of overwriting, Steph Locke has a guide to
keeping up with changes, but still autodeploying the docshttps://
itsalocke.com/
auto-deploying-documentation-better-change-tracking-artefacts/

HTH

Robert

On Fri, Dec 23, 2016 at 1:14 PM Laurent Gatto <lg390 at cam.ac.uk> wrote:


    Dear Sean and Robert,

    On 23 December 2016 17:24, Robert M. Flight wrote:

    > Yes, this seems like a time where using a non-standard site

    directory

    > on Github is useful, or as Sean said, using a separate branch to

    serve

    > the html content.

    It's not clear to me how a separate branch is the solution. In
    git-svn,
    devel, release_3_4, ... are just that, different branches. How
    would you
    set a gh-pages branch that contains a single dir so that it doesn't
    conflict with master?

    If I could set branch-specific directives in my .gitignore file,
    then I
    would set this up for the Bioc branches. This seems to suggest it
    is
    possible, but I haven't tried yet

    http://stackoverflow.com/questions/1836742/
    using-git-how-do-i-ignore-a-file-in-one-branch-but-have-it-committed-in-another

    Would it be possible to set something on the svn side to ignore/
    delete
    the docs dir automatically, independently of what git does?

    Laurent

    > -Robert
    >
    > On Fri, Dec 23, 2016 at 12:19 PM Sean Davis <seandavi at gmail.com>

    wrote:

    >
    >  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
    >  >>>
    >  >>>  ________________________________________
    >  >>>  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

    >  >
    >  >
    >  > --
    >  > Laurent Gatto | @lgatt0
    >  > http://cpu.sysbiol.cam.ac.uk/
    >  > http://lgatto.github.io/
    >  >
    >  > _______________________________________________
    >  > 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

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

Dear Sean and Robert,

On 23 December 2016 17:24, Robert M. Flight wrote:

Yes, this seems like a time where using a non-standard site directory
on Github is useful, or as Sean said, using a separate branch to serve
the html content.

It's not clear to me how a separate branch is the solution. In git-svn,
devel, release_3_4, ... are just that, different branches. How would you
set a gh-pages branch that contains a single dir so that it doesn't
conflict with master?

If I could set branch-specific directives in my .gitignore file, then I
would set this up for the Bioc branches. This seems to suggest it is
possible, but I haven't tried yet

 http://stackoverflow.com/questions/1836742/using-git-how-do-i-ignore-a-file-in-one-branch-but-have-it-committed-in-another

Would it be possible to set something on the svn side to ignore/delete
the docs dir automatically, independently of what git does?

Laurent

-Robert

On Fri, Dec 23, 2016 at 12:19 PM Sean Davis <seandavi at gmail.com> wrote:

    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
    >>>
    >>>    ________________________________________
    >>>    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

    >
    >
    > --
    > Laurent Gatto | @lgatt0
    > http://cpu.sysbiol.cam.ac.uk/
    > http://lgatto.github.io/
    >
    > _______________________________________________
    > Bioc-devel at r-project.org mailing list
    > https://stat.ethz.ch/mailman/listinfo/bioc-devel

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