docs: Switch website from pkgdown to mkdocs-material with altdoc

[etiennebacher]

Close #137

See progress here: https://etiennebacher.github.io/r-polars/site No longer available (I removed the files so that this can be merged)

[eitsupi]

Just a question: do we need to commit this large number of Markdown files?

[etiennebacher]

All markdown files are used when we run mkdocs build (called by altdoc::preview()) so that it can build the docs/site folder. I'm still thinking of the best way to write a github action that would create all the docs automatically without having to commit anything other than in the usual R development workflow (like pkgdown).

[etiennebacher]

But for now I commit everything because I put this branch on github pages so that we can have a live demo

[eitsupi]

Thanks, it make sense now.

[etiennebacher]

Note to self: we still need a docs folder in the main branch that contains mkdocs.yaml and a subfolder docs containing custom CSS and logo because that's crucial to structure our docs. What we don't need in this folder are:

• the files for "Reference" because they can be generated automatically
• the vignettes because can be converted automatically -> caching them is not a good idea because even if the vignette in itself doesn't change, the functions used inside can change
• the site subfolder because it's generated by mkdocs build

[etiennebacher]

Looks like the CI for documentation is ready, it only errors because I don't have the rights to create a branch on this repo

[eitsupi]

Could the generated files be added to gitignore and then deleted?

[etiennebacher]

I think the preview is still useful for now so if I delete the files we won't have it anymore. Do we do all the cleaning in R files here before merging? @sorhawell

[sorhawell]

Do we do all the cleaning in R files here before merging?

I didn't quite get this question. How can I help to bring this live, what buttons should I press to give branch permission?

Currently pkgdown pushes to rpolars github.io with secrets.DEPLOY_DOCS token. Could you use that from the new workflow?

[etiennebacher]

Currently pkgdown pushes to rpolars github.io with secrets.DEPLOY_DOCS token. Could you use that from the new workflow?

We now updated the workflow to also push to this repo. I removed most of the docs files (that will be automatically generated by the workflow) so once @eitsupi's comment is addressed I think we can merge this

[eitsupi]

Thank you for tackling this tough task! I would like to try a local build later and push some minor updates.

[etiennebacher]

I would like to try a local build later and push some minor updates.

I'd like to implement the "About" page mentioned in this comment in a future PR, unless you want to do it here

[eitsupi]

I have made some minor updates.

• List R package dependencies in the DESCRIPTION file (this is a common practice in the pkgdown workflow)
• Rbuildignore and gitignore some files
  • Since mkdocs.yml is both the template and an auto generated file, CI was set up to copy the template mkdocs.orig.yml to mkdocs.yml just before executing altdoc::update_docs(). Perhaps it would be worth adding a new feature that could specify a template for altdoc::update_docs()
• To check the results of the CI run, I overwrote the workflow definition file with the existing pkgdown one.

If there are no problems with this change, it is working well and can be merged. Great job!

[etiennebacher]

Looks great, thanks for cleaning all of this @eitsupi, it's much better to keep a clear template like this. One thing: should we rename pkgdown.yml to something else?

Otherwise, if tests pass, I'm ok to merge

[eitsupi]

One thing: should we rename pkgdown.yml to something else?

My understanding is that CI will not run if renamed in this PR. It would make sense to change this in a follow-up PR after merging this.

[sorhawell]

Looking forward to see the official r-polars. pkgdown was a good stepping stone, but just deprecate it whenever ready.

Great work !

[eitsupi]

Ok, let's try merging this!

[etiennebacher]

Looks like it worked! :tada: :tada:

I'll make another PR soon with various tweaks

[vincentarelbundock]

This is amazing work and a massive improvement over pkgdown. Thanks!

[eitsupi]

Awesome!

(I forgot to remove the dev doc badge from README...)