docs: port docs to mkdocs

[MrPowers]

Description

This PR ports the docs to mkdocs. We'd like to be able to write docs in Markdown.

A previous PR ported the docs to mkBook, but we think mkdocs is better, so the mkBook PR will be closed.

Related Issue(s)

n/a

Documentation

n/a

[github-actions]

ACTION NEEDED

delta-rs follows the Conventional Commits specification for release automation.

The PR title and description are used as the merge commit message. Please update your PR title and description to match the specification.

[MrPowers]

You can build the new docs and run them locally with mkdocs serve.

The new docs look quite similar to the existing docs, but they're easier to navigate and have a URL structure that's better for SEO.

[cmackenzie1]

Not sure if there has been much discussion around hosting the site but I'd be happy to help setup Cloudflare Pages (disclaimer, I work at Cloudfare)

[MrPowers]

@cmackenzie1 - thanks for the offer. I think the original idea was to just use GitHub pages and the same URL where the current docs are hosted: https://delta-io.github.io/delta-rs/python/

I am open to other ideas from the community of course.

[rtyler]

@MrPowers since this is at the root of the tree and not in the python/ directory. Is this where I can start landing some Rust documentation as well? I have been pining to improve the documentation situation there lately as well

[MrPowers]

@rtyler - yea, would be great to use this as an opportunity to improve the Rust documentation as well.

Here is how Polars organizes their URLs:

• User guide: https://pola-rs.github.io/polars-book/user-guide/
• Python documentation: https://pola-rs.github.io/polars/py-polars/html/reference/
• Rust documentation: https://pola-rs.github.io/polars/polars/

The user guide has tabbed code blocks to switch between languages:

Would you be OK if we organize the delta-rs documentation in a similar manner?

[rtyler]

Since this is coming into the root of the tree and is not yet published anywhere. I want to merge this and continue collaborating around it.

[wjones127]

Since this is coming into the root of the tree and is not yet published anywhere. I want to merge this and continue collaborating around it.

+1. I started looking into adding Python API reference to this, but it turns out it will require quite a few fixes to our type stubs, so it's best this happens in a new PR.