Skip to content

[Bioc-devel] Reference manual as HTML

11 messages · Ludwig Geistlinger, Stuart Lee, Henrik Bengtsson +4 more

Original
Ludwig Geistlinger
# 
Dear Bioc-Team,


I repeatedly wondered whether it would be possible to display the reference manual
as HTML instead of PDF on a package's landing page. This is already possible for vignettes.

HTML reference manuals have at least two advantages:

1. links to functions of other package in the man pages of my package would
actually work. Links to functions / classes of other packages of the form

\code{\link{p.adjust}}

or

\code{\linkS4class{SummarizedExperiment}}

within the pdf reference manual currently point nowhere (bring me back to the
first page of the pdf). Within the html reference manual

help(package="myPackage", help_type="html")

these links work as expected, ie bring me to the help pages of functions / classes
of other packages.

2. I could easily refer users to the documentation link of a specific function
(without them having to search through the pdf) such as "check the documentation of
the DESeq function here: https://rdrr.io/bioc/DESeq2/man/DESeq.html".

(where the link would be preferably: bioconductor.org/packages/DESeq2/man/DESeq.html).


Thank you,

Ludwig
Laurent Gatto
# 
I think this would be very useful. This is one of the reasons I create pkgdown sites for my packages: manual pages, news and html vignettes are readily available for all (including me) to browse.

Best wishes,

Laurent
Martin Morgan
# 
Our recollection is that there is no 'flag' in R CMD build to create HTML rather than PDF vignettes; without that it would be non-trivial to create html output, e.g., links across pages. (I *think* the installed package html help pages are generated on the fly...)

What is your experience with pkgdown?

Martin

?On 9/25/19, 9:44 AM, "Bioc-devel on behalf of Laurent Gatto" <bioc-devel-bounces at r-project.org on behalf of laurent.gatto at uclouvain.be> wrote:

    I think this would be very useful. This is one of the reasons I create pkgdown sites for my packages: manual pages, news and html vignettes are readily available for all (including me) to browse.
    
    Best wishes,
    
    Laurent
Stuart Lee
# 
Chiming in to say +1 to this. I also use pkgdown for the same purpose as Laurent. With some kind of CI service you can automate the build of the website after a successful R CMD CHECK. Not sure how tricky this would be to integrate with Bioconductor's build system.
Henrik Bengtsson
#
On Wed, Sep 25, 2019 at 2:28 PM Stuart Lee <lee.s at wehi.edu.au> wrote:
FYI, 'pkgdown' only supports vignettes that are written in the
Rmarkdown format (https://github.com/r-lib/pkgdown/issues/781).

/Henrik
Martin Morgan
# 
Oops, I said 'vignettes' but meant the reference manual. Html vignettes (from appropriate Rmd files) are have been available for a number of years.

Martin
?On 9/25/19, 5:10 PM, "Martin Morgan" <mtmorgan.bioc at gmail.com> wrote:
Our recollection is that there is no 'flag' in R CMD build to create HTML rather than PDF vignettes; without that it would be non-trivial to create html output, e.g., links across pages. (I *think* the installed package html help pages are generated on the fly...)
    
    What is your experience with pkgdown?
    
    Martin
    
    ?On 9/25/19, 9:44 AM, "Bioc-devel on behalf of Laurent Gatto" <bioc-devel-bounces at r-project.org on behalf of laurent.gatto at uclouvain.be> wrote:
    
        I think this would be very useful. This is one of the reasons I create pkgdown sites for my packages: manual pages, news and html vignettes are readily available for all (including me) to browse.
        
        Best wishes,
        
        Laurent
Laurent Gatto
# 
My experience with pkgdown is very positive. As mentioned by Stuart, I use travis to automatically build the webpage after a successful check and serve it as a gh-page.

I find it particularly useful as it displays the devel version of the vignettes and individual manual pages, which often come handy to answer questions related to new features or bug fixes and to add a link to the relevant manual page (rather than a large pdf) or vignette section. The webpage is also a good starting point to learn about new packages, as all the documentation sources, README, vignettes and individual man pages (which can easily be overwhelming for large packages) are readily available to read and search.

Laurent
Martin Maechler
# 
> Our recollection is that there is no 'flag' in R CMD build to create HTML rather than PDF vignettes; without that it would be non-trivial to create html output, e.g., links across pages. (I *think* the installed package html help pages are generated on the fly...)

Yes, by default.
But you may (or not) remember that for R itself, I (and my
university, ETH Zurich) have provided static HTML help pages and
manuals since "forever" -> https://stat.ethz.ch/R-manual/
and my cron job that creates (and daily updates) them "starts
with"

  ../R/configure --with-prebuilt-html

As it does provide static html help pages for all "base R" +
Recommended packages,

 see, e.g., https://stat.ethz.ch/R-manual/R-devel/doc/html/packages.html

it should not be hard to have it do the same for all other
packages in principle.

"The other R Core" Martin

Martin Maechler
ETH Zurich


    > What is your experience with pkgdown?

    > Martin

    > ?On 9/25/19, 9:44 AM, "Bioc-devel on behalf of Laurent Gatto" <bioc-devel-bounces at r-project.org on behalf of laurent.gatto at uclouvain.be> wrote:

    > I think this would be very useful. This is one of the reasons I create pkgdown sites for my packages: manual pages, news and html vignettes are readily available for all (including me) to browse.
    
    > Best wishes,
    
    > Laurent
    
    > ________________________________________
    > From: Bioc-devel <bioc-devel-bounces at r-project.org> on behalf of Ludwig Geistlinger <Ludwig.Geistlinger at sph.cuny.edu>
    > Sent: 25 September 2019 13:31
    > To: bioc-devel at r-project.org
    > Subject: [Bioc-devel] Reference manual as HTML
    
    > Dear Bioc-Team,
    
    
    > I repeatedly wondered whether it would be possible to display the reference manual
    > as HTML instead of PDF on a package's landing page. This is already possible for vignettes.
    
    > HTML reference manuals have at least two advantages:
    
    > 1. links to functions of other package in the man pages of my package would
    > actually work. Links to functions / classes of other packages of the form
    
    > \code{\link{p.adjust}}
    
    > or
    
    > \code{\linkS4class{SummarizedExperiment}}
    
    > within the pdf reference manual currently point nowhere (bring me back to the
    > first page of the pdf). Within the html reference manual
    
    > help(package="myPackage", help_type="html")
    
    > these links work as expected, ie bring me to the help pages of functions / classes
    > of other packages.
    
    > 2. I could easily refer users to the documentation link of a specific function
    > (without them having to search through the pdf) such as "check the documentation of
    > the DESeq function here: https://rdrr.io/bioc/DESeq2/man/DESeq.html".
    
    > (where the link would be preferably: bioconductor.org/packages/DESeq2/man/DESeq.html).
    
    
    > Thank you,
    
    > Ludwig
    
    > [[alternative HTML version deleted]]
    
    > _______________________________________________
    > 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
    
    > _______________________________________________
    > Bioc-devel at r-project.org mailing list
    > https://stat.ethz.ch/mailman/listinfo/bioc-devel
Hervé Pagès
# 
and let's not forget the rdrr site that provides HTML versions of all R 
package man pages in the known world:

   https://rdrr.io/bioc/DESeq2/man/DESeq.html

Unfortunately the links across man pages are not clickable :-/

H.
On 9/26/19 06:19, Martin Maechler wrote:

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Laurent Gatto
    

    

      
      #
    

  


  

      
But it has been  badly out-of-data in the past, not sure devel is available and buggy (examples don't run, despite the Run button and outdated installation instructions still using `source("https://bioconductor.org/biocLite.R")`)

Laurent

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Hervé Pagès
    

    

      
      #
    

  


  

      
Hopefully they'll remedy these problems. They've clearly put a enormous 
effort on this.

It sounds like a non-trivial effort to generate the tens of thousands of 
Bioconductor man pages in HTML and keep them in sync with whatever comes 
out of the nightly builds every day. Plus, if we want the links in the 
man pages to work, we would need to also generate and host the HTML man 
pages of all CRAN dependencies. I'm not sure we (the core team) have the 
resource for that. Maybe an easier/cheaper path is to rely on some 
already existing resource like rdrr.io (and maybe help them by reporting 
problems etc...)

Best,
H.

        
On 9/26/19 22:35, Laurent Gatto wrote: