WIP: mkdocs & altdoc & makefile

[vincentarelbundock]

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]

This PR is a first attempt to address #63

[zeileis]

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]

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]

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]

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]

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]

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]

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]

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?