Website

[grantmcdermott]

In keeping with plot2's goal to be an attractive lightweight plotting option, the website should help to offload content that is adding unnecessary bulk to the package itself. A case in point is the fact that all the images in the README are currently pushing the installation tarball to several MiBs.

Serving content external to the package also means that we shouldn't use conventional R vignettes (which would get bundled with the installation tarball). So I'm not sure how well this workflow jibes with standard R website builders like pkgdown and altdoc.

Some options:

• Build a docs/ folder locally and serve it through github-pages. (Can perhaps still be automated with GH Actions?)
• Use a Quarto book format like @vincentarelbundock did for marginaleffects link. Vincent, curious about your experiences here.
• A gallery-type website (see #59).

[vincentarelbundock]

Easiest would probably be to add vignettes/ to .Rbuildignore.

It was kind of hard to do a Quarto book, and I had to write a lot of custom scripts. Over the next few months, @rempsych and I will be working on improving altdoc in several ways, including allowing for Quarto book output.

I don't plan to use pkgdown for complicated packages in the future.

If you want, I can try to use altdoc to produce a minimalist website for plot2 with Material MkDocs.

[grantmcdermott]

If you want, I can try to use altdoc to produce a minimalist website for plot2 with Material MkDocs.

Cool, thanks! For a MWE feel free to move the README examples to the equivalent of a vignette.

(One lingering concern I have about Material MkDocs is that this pulls in a Python dependency. Am I remembering correctly, here?)

[zeileis]

We had the same problem with our colorspace package: We started writing quite a few vignettes which became too large for the package. So we turned them into a pkgdown page: https://colorspace.R-Forge.R-project.org/.

The Get started vignette is the only vignette that is also contained in the package, all others are in .Rbuildignore. It has a short overview, some teaser images, and (absolute) links to the other vignettes on R-Forge. Thus, there is the same content just rendered differently on CRAN and R-Forge:

• https://CRAN.R-project.org/web/packages/colorspace/vignettes/colorspace.html
• http://colorspace.R-Forge.R-project.org/articles/colorspace.html

This setup worked quite well for us and we turned the vignettes eventually also into a paper.

[vincentarelbundock]

That looks beautiful, @zeileis !

[etiennebacher]

Quickly chiming in here to say that I have a different workflow from those above when I use altdoc. For example in conductor I don't have any vignettes. I have a docs folder where I directly write and update the documentation when needed. This folder is in .Rbuildignore so the package is very light (< 100 KB, which I think can be considered light). This means that I don't have any vignette that the user can read from the CRAN page or somewhere else.

I don't have any github actions for this, even though I could. I just need to remember to run altdoc::update_docs() when I change the docs in the R files or the NEWS for instance. This uses docsify, not mkdocs so no Python dep to setup.

Example website: https://conductor.etiennebacher.com/

[vincentarelbundock]

@etiennebacher GitHub only allows me to render directly from docs/ but both use_mkdocs() and update_docs() seem to on docs/docs and docs/site.

How do you deal with that? In my PR i use a clunky Makefile to copy the contents of docs/site/* to the root of a different branch, but that's kind of annoying.

[vincentarelbundock]

@etiennebacher GitHub only allows me to render directly from docs/ but both use_mkdocs() and update_docs() seem to on docs/docs and docs/site.

How do you deal with that? In my PR i use a clunky Makefile to copy the contents of docs/site/* to the root of a different branch, but that's kind of annoying.

[etiennebacher]

I actually never had this problem because I never used mkdocs for one of my packages so I don't have a clear solution for this. Maybe altdoc should put both folders in the top directory? In any case I can open an issue about this in altdoc repo to not bother the conversation here

[grantmcdermott]

Closed by #80.