search

grantmcdermott / tinyplot

Lightweight extension of the base R graphics system
https://grantmcdermott.com/tinyplot
Apache License 2.0
208 stars 7 forks source link

WIP: mkdocs & altdoc & makefile #64

Closed vincentarelbundock closed 7 months ago

vincentarelbundock commented 11 months ago

Building the website requires local install of mkdocs and mkdocs-material. But of course the end-user does not need to install any of that.

I also added a Makefile with useful commands like make deploy. I think it should be pretty self-explanatory.

The rendered website is here: https://vincentarelbundock.github.io/plot2/

vincentarelbundock commented 11 months ago

This PR is a first attempt to address https://github.com/grantmcdermott/plot2/issues/63

zeileis commented 11 months ago

Disclaimer: I haven't worked with mkdocs or altdoc yet, just read about them.

Is there a way to include printed and graphical output in the examples? That's a feature that I quite like about pkdown.

grantmcdermott commented 11 months ago

Nice! Thanks @vincentarelbundock , this is a great proof of concept.

I'm still quite leery of taking on a Python dependency for the website. But I do like the mkdocs look and layout.

It seems that there is still some good discussion happening at #63, so let's wait to see what comes of that.

grantmcdermott commented 11 months ago

Is there a way to include printed and graphical output in the examples?

@zeileis I don't quite follow. Do you mean automatically rendered/knitted code as per a qmd or Rmd doc?

zeileis commented 11 months ago

Yes. For illustration consider the examples at the end of:

https://vincentarelbundock.github.io/plot2/reference/

These are just shown verbatim. However, the examples from this manual page in the pkgdown page for colorspace are actually run with output/graphics included:

http://colorspace.R-Forge.R-project.org/reference/contrast_ratio.html

grantmcdermott commented 11 months ago

Ah, got it thanks.

I think Vincent and Etienne hacked together a script for doing this with the r-polars docs (but I may just be misremembering)..

vincentarelbundock commented 11 months ago

Yep, we rolled our own script for polars, but rendering examples in the function documentation is not super easy to do right now.

The reason I made this PR using altdoc is that I've been hungry for a serious competitor to pkgdown, and that I plan to spend some serious time on altdoc in the coming months. So this was an excuse to try it out and hit the pain points in a relatively simple package (plot2).

So yeah, currently it doesn't have all the features we probably want eventually. But feature parity is a matter of months rather than years, I think.

vincentarelbundock commented 11 months ago

huh, that sounded a bit dry. To be clear, I'm perfectly happy with doing pkgdown for this project. I was just explaining where I was coming from...

zeileis commented 11 months ago

Thanks for the explanation, Vincent, very helpful. And also to be clear: I'm also fine with trying out something other than pkgdown, especially when I know that you are working on it!

I just thought that for a graphics package it would be nice to show the example plots in the manual web pages. But this is not urgent and might be an incentive to improve altdoc?