Adding mkdocs into guides and cookiecutter template

[Samreay]

Should resolve #648, and Ive tested the docs build, copier, and jekyll site rebuild and it seems good. Welcome some more eyes on it though!

---

📚 Documentation preview 📚: https://scientific-python-cookie--662.org.readthedocs.build/

[Copilot]

Pull Request Overview

This PR adds MkDocs as a documentation option to the cookiecutter template, allowing users to choose between Sphinx and MkDocs when creating a new project. This addresses issue #648 by providing an alternative documentation framework that is simpler to set up and increasingly popular in the Python community.

Key Changes:

• Added MkDocs as a new documentation tool choice in the cookiecutter template
• Created MkDocs-specific template files and configuration
• Updated documentation guides to cover both Sphinx and MkDocs options

Reviewed Changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
cookiecutter.json	Added "docs" option with sphinx/mkdocs choices
copier.yml	Added docs selection configuration
{{cookiecutter.project_name}}/mkdocs.yml	Template for MkDocs configuration file
{{cookiecutter.project_name}}/docs/index.md	MkDocs homepage template
{{cookiecutter.project_name}}/docs/api.md	MkDocs API documentation template
{{cookiecutter.project_name}}/src/.../example.py	Example class with docstrings for API generation
{{cookiecutter.project_name}}/pyproject.toml	Conditional docs dependencies based on selected tool
{{cookiecutter.project_name}}/noxfile.py	Conditional nox sessions for Sphinx vs MkDocs
{{cookiecutter.project_name}}/README.md	Removed Sphinx-specific comment
{{cookiecutter.project_name}}/.readthedocs.yaml	Conditional build commands for each docs tool
noxfile.py	Added Docs enum and parametrized all test sessions with docs option
tests/test_readthedocs.py	Removed obsolete RTD104 tests
docs/pages/tutorials/docs.md	Updated tutorial to mention both Sphinx and MkDocs
docs/pages/guides/docs.md	Comprehensive guide covering both documentation frameworks
docs/README.md	Updated rbenv version

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull Request Overview

Copilot reviewed 17 out of 19 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The configuration comment claims this feature enables URL auto-update as users scroll, but navigation.tracking actually updates the URL to match the active navigation item when navigating sections, not during scrolling.

[henryiii]

FYI, you might want to look into this and see if it's correct.

[Samreay]

Have just tried turning this feature on and off in my own repo and can confirm that with the feature and can confirm that its responsible for my URL updates as I scroll through different anchors

[henryiii]

Thanks! Might iterate on it a bit more eventually, but it's great to have!

[Samreay]

Thanks Henry! And from the number of commits you had to add, my apologies for all the things I missed

[henryiii]

That's fine, you got it most of the way there (and got all the stuff I'm not as familiar with done, like setup for mkdocs), most of it was just filling out all the little places that get affected with a new option.

[henryiii]

I hadn't noticed that MkDocs became basically unmaintained in August 2024, and Material for MkDocs is being replaced by zensical, and will be retired in 12 months. We probably should either move this to Zensical if that makes sense, or remove it until a replacement is available? For now we probably should just put a little warning about using MkDocs.

[Samreay]

TIL about zensical! Yeah this makes sense, and I'd be happy to do a PR for a swap over when the tool is out of alpha. I've joined the newsletter to stay in the loop. Happy for a PR now adding a note to the Mkdocs section? I see they've got a lot done, but the two main gaps IMHO are the current lack of example gallery and jupyter tutorials. Seems like they'll need the plugin system working for this.

[henryiii]

Yes, we should add a little note block, and I would also like for the sections to be arranged of the two different tabs have the same order. I noticed that the requirements was first in one and near the bottom and the other.

I can do it (eventually) if you can’t get to it.

[Samreay]

PR added to your workload! #688