feat(presets): group MkDocs and Material for MkDocs

[HonkingGoose]

Changes

• Group MkDocs and Material for MkDocs packages together in a new preset
• Add the new preset to the group:recommended preset

Context

requirements.txt example

Here's a example of a requirements.txt that Renovate could update:

mkdocs-material==9.5.19
mkdocs==1.6.0

Why group the packages?

Renovate should update both these packages at the same time, because mkdocs-material sometimes depends on a newer version of mkdocs.

For example, to upgrade to mkdocs-material==9.5.19 I first needed to update to mkdocs==1.6.0.

Context about mkdocs-material pinning the version of mkdocs

There's a lot of info and discussion about the version pinning here:

• Support mkdocs 1.6.0 squidfunk/mkdocs-material#7076

Possible bounded package of mkdocs-material[bounded] in the future

The maintainer of Material for MkDocs may decide to split their package into a [stable] bounded package, and the default mkdocs-material that works the same as currently.

Here's the full comment from @squidfunk: ¹

@sisp Thanks again for your input! We'll re-evaluate this in the near future. Please understand that we're currently very, very heavily working in the background, doing a large refactor of some of the project's features, documentation, working on an entirely new search etc., and other big things we have not communicated yet.

We're also starting to build a team to keep up with the need and demands of enterprises and organizations, and all of this is a lot, lot, lot of work. We're still only 3-4 (mostly part-time) individuals, depending on how you count, with me working full-time on Material for MkDocs.

Given this context, I hope you understand that changing the way we manage dependencies is currently not at the top of our priority list. However, I've heard the criticism and we'll likely offer both options in the future. Probably something like:

pip install mkdocs-material[stable] # bounded
pip install mkdocs-material         # unbounded

The specifics still need to be worked out, and while I understand that you have deep knowledge of Python package management, most Material for MkDocs users don't. They just want it to work, and for this we try to make it as simple as possible. It's after all a strategic decision. As said, we're going to offer more fine-grained options in the future, but for the time being this issue should be resolved.

The new bounded behavior will go into it's own package, so my new group:MkDocsAndMaterial preset should keep working.

Documentation (please check one with an [x])

• I have updated the documentation, or
• No documentation update is required

How I've tested my work (please select one)

I have verified these changes via:

• Code inspection only, or
• Newly added/modified unit tests, or
• No unit tests but ran on a real repository, or
• Both unit tests + ran on a real repository

Footnotes

1. Maintainer comment on Material for MkDocs repo about possible bounded package [stable] ↩

[viceice]

I don't think we need a new group. they don't need to be grouped

[rarkins]

I don't think we need a new group. they don't need to be grouped

Are you sure? The mkdocs material we're on only supports Mkdocs 1.5. The next mkdocs material only supports mkdocs 1.6. In this case and likely at more times in future we'll need to update them together.

[HonkingGoose]

These comments from two maintainers of Material for MkDocs seem relevant for us here. So I'm copy/pasting them here, with some small edits. For the originals see the links in the footnotes:

From @alexvoss: ¹

... pip install 'mkdocs>=1.6.0' 'mkdocs-material' is the scenario where someone forces a version of MkDocs that Material has not been tested with. Everyone who installs the version that Material has been tested against will be fine. No point telling people they can use 1.6 when the result of that is as yet unknown. @squidfunk is doing the prudent thing here and has already pledged to look at what the issues might be. ...

From @squidfunk: ²

... In our installation guide, we do not list in any place that you should install mkdocs explicitly – au contraire, you should install mkdocs-material and let us pick the supported latest version. This way, we can ensure that all plugins work, and yes, we will upgrade to 1.6, but with tens of thousands of projects using our software, we need to be careful about that ✌️

Footnotes

1. Comment from @alexvoss ↩

2. Comment from @squidfunk ↩

[viceice]

I don't think we need a new group. they don't need to be grouped

Are you sure? The mkdocs material we're on only supports Mkdocs 1.5. The next mkdocs material only supports mkdocs 1.6. In this case and likely at more times in future we'll need to update them together.

yes, the new material version support mkdocs <2

[viceice]

ok, so we should remove mkdocs from our deps and let poetry/ material a proper version.

will do tomorrow

[HonkingGoose]

I don't think we need a new group. they don't need to be grouped

Are you sure? The mkdocs material we're on only supports Mkdocs 1.5. The next mkdocs material only supports mkdocs 1.6. In this case and likely at more times in future we'll need to update them together.

yes, the new material version support mkdocs <2

I suppose that mkdocs 2.0.0 and mkdocs-material Version That Supports mkdocs 2.0.0 will still need to be grouped together though?

ok, so we should remove mkdocs from our deps and let poetry/ material a proper version.

will do tomorrow

I don't know if this is a good idea or not. I guess pinning to a version makes it easier to debug when things go wrong, and also means we know precisely what version we're using of both packages? But I'm probably misunderstanding something here. 😄

[HonkingGoose]

I'm marking this PR as draft for now, until we're clear on what we want. 😄 This also stops us from accidentally merging work before it's good to go.