Provide first-class tutorial for mkdocs, not just for sphinx

[Samreay]

Hi team! Given the popularity of mkdocs continuing to eclipse that of Sphinx (see below image), I think it would be very worthwhile to add a proper tutorial for setting up Mkdocs, possibly even moving it to the default recommended documentation builder down the line.

I would be happy to contribute to this, having used mkdocs for all my projects. Would the team be open for a contribution on this front? I am happy to both write a guide for the documentation, and extend the cookie cutter to give a sphinx/mkdocs option

[henryiii]

Yes, that's been on the "someday" list for a while now. I was thinking it could be tabs, like how we do backends, on the guide. I think Sphinx still is pretty strongly in the lead when it comes to scientific software, but this might help change that. :)

[Samreay]

Hey @henryiii, I'm almost ready to get a PR out for this and just wanted to check something first. I am trying to add some tabs to allow Sphinx or MkDocs instructions, and I notice that at the readthedocs section there are tabs for uv+Sphinx and pip+Sphinx:

However in the docs.md file, I do not see any tabs present, only a code_fence and then a direct yaml insert. Any chance you can point me to what I'm missing?

[henryiii]

Timing: d537043 - we deploy irregularly. Dep groups required the pip method be dropped (since rtd doesn’t have native support, though pip does)

[Samreay]

Ah that helps! With the removal of the pip method, does that mean that RTD104 in the markdown below those commit changes should be removed as well?

[Samreay]

Good news @henryiii - just in the nick of time for the weekend over here in Aus, but I've got something that would be great to have some eyes on when you have the time :) #662