package documentation with litedown

[jangorecki]

it's possible that litedown will have its own implementation of package documentation someday.

Originally posted by @yihui in https://github.com/yihui/litedown/issues/22#issuecomment-2334876365

Filling out new issue so it is easier to be subscribed to this particular feature. I would find it very useful. pkgdown broke my CI setup at least twice by pulling in new OS deps. Exactly the problem where lite version would fit to improve reliability.

On a side note, base R has functions for package documentation built-in. We are using that inside data.table CI pipeline to generate lightweight html documentation, simply by installing pkg with INSTALL_opts="--html". https://github.com/Rdatatable/data.table/blob/619ca739aa7c176230cac9fd097a466f0804f7fa/.gitlab-ci.yml#L352C143-L352C164 https://rdatatable.gitlab.io/data.table/library/data.table/html/00Index.html

[llrs]

Another option is to use the new pkg2HTML() that CRAN wants to use to generate the manual pages for all CRAN packages. It also renders a single html page with all the help pages. HTH both

[jangorecki]

@llrs thanks for informing on that. Looks nice, and great that it is in base R. Although for publishing online as a website this single page may not be always ideal solution.

[erikcs]

Just seconding @jangorecki's sentiment that a lightweight online documentation generator would be great. Though, for people to migrate I think it would need to have functionality to retain existing URL layout so external links referring to current docs don't break. (We currently lock in a pkgdown version so our build doesn't break when a new version is released - I'm perfectly happy with pkgdown 1.5 as long as that keeps working).

[yihui]

I've implemented the basic components of pkgdown, and will comment more tomorrow (need to go to sleep now).

[jangorecki]

@yihui maybe we could still have pkg_vignettes() to render all vignettes?

[yihui]

@jangorecki My current idea is that vignettes can be the base of the pkgdown site, meaning that the site is generated under the vignettes/ directory. The site can be either a book (using individual vignettes as chapters), or a website (each vignette is a page). This eliminates the need for pkg_vignettes().

Note that the site could be either automatically generated as a book (via R CMD build) by using the vignette engine litedown::book, or manually generated by litedown::fuse_book()/fuse_site() (e.g., in Github Action). Rmd files that don't have \VignetteEngine{} specified in them will be ignored by R's vignette builder (I think they will also be ignored by R CMD build---I haven't verified it yet), so you can have arbitrary Rmd files under vignettes/ and they won't be picked up by R CMD build but you can still build the site/book by yourself.

I've implemented the basic components of pkgdown, and will comment more tomorrow (need to go to sleep now).

The comments that I intended to add are:

The litedown::pkg_* functions are the basic components of a package website. It's just that litedown doesn't have an opinion on how these pkg_* components should be organized, and this decision is left to users.

• One possibility is put these components in a book and they can be wherever you want (e.g., in the appendix).

• Another possibility is a website like pkgdown, but built with fuse_site(). You can call pkg_*() functions in any code chunk in any Rmd file, e.g., pkg_desc() in about.Rmd, pkg_news() in news.Rmd, and pkg_manual() in reference.Rmd, etc.

The main difference between a book and a website is that the former is a single HTML file, and the latter is multiple (one .html for one .Rmd or .md).