fix: pin mkdocs<2.0 and mkdocs-material<10, add NO_MKDOCS_2_WARNING t…

[Acuspeedster]

PR: Pin MkDocs below 2.0 and suppress deprecation warnings in all CI doc steps

Branch: fix/pin-mkdocs-below-2-pin-material
Fixes: #2104 Upgrade trestle to use MkDocs 2.0
Related open PR: #2131

---

Problem

MkDocs 2.0 was released but the MkDocs plugin ecosystem most critically Material for MkDocs (the theme driving this project's documentation) has not yet migrated to support it. Installing MkDocs 2.0 breaks the docs build entirely. Additionally, MkDocs 1.x now emits a FutureWarning about the upcoming 2.0 release during every build, which can surface as noise in CI output.

Without an explicit upper-bound pin on mkdocs, pip is free to resolve mkdocs>=1.6.0 to mkdocs 2.0.x, causing docs builds to silently break for any new contributor or in any clean CI environment.

---

What existing PR #2131 did (and missed)

PR #2131 by @Aditya-Aryan-6914 was a step in the right direction but has two significant gaps:

Gap 1: mkdocs-material left unpinned

#2131 pinned mkdocs>=1.6.0,<2.0.0 but left mkdocs-material completely unconstrained:

# PR #2131 material still has no upper bound
"mkdocs-material",

The Material for MkDocs package will eventually release a version requiring MkDocs ≥ 2.0.0. When that happens, pip resolving mkdocs-material to the newest release would pull in MkDocs 2.0 as a transitive dependency, silently defeating the <2.0.0 pin on mkdocs itself. The mkdocs-material pin is just as critical as the mkdocs pin.

Gap 2: Check if dirty (mkdocs) step not covered

#2131 added NO_MKDOCS_2_WARNING: 1 to the Validate website content (mkdocs) step in python-test.yml but missed the very next step, Check if dirty (mkdocs), in the same file. That step runs make check-for-changes, which internally calls hatch run docs:automation and hatch run docs:build both of which invoke mkdocs build and therefore emit the deprecation warning.

# python-test.yml Check if dirty step NOT covered by PR #2131
- name: Check if dirty (mkdocs)
  run: |
    make check-for-changes

---

What this PR does

1. Pins mkdocs AND mkdocs-material in pyproject.toml

# Before
"mkdocs>=1.6.0",
"mkdocs-material",

# After
"mkdocs>=1.6.0,<2.0.0",
"mkdocs-material>=9.0.0,<10.0.0",

• mkdocs<2.0.0 prevents pip from resolving the package to MkDocs 2.x until the full plugin ecosystem is MkDocs-2.0-ready.
• mkdocs-material>=9.0.0,<10.0.0 keeps Material pinned to the MkDocs-1.x-compatible 9.x series. Material v9.x is the current stable release line and is fully tested with MkDocs 1.5/1.6. Setting <10.0.0 ensures a future Material 10 release (which is expected to target MkDocs 2.0) does not get installed and pull in MkDocs 2.x as a transitive dependency.

2. Adds NO_MKDOCS_2_WARNING: '1' to all four mkdocs-invoking CI steps

Workflow	Step	Covered by #2131?	Covered here?
python-test.yml	Validate website content (mkdocs)	✅	✅
python-test.yml	Check if dirty (mkdocs)	❌ missed	✅
python-push.yml	Validate website content (mkdocs)	✅	✅
docs-update.yml	Create release (mike deploy → mkdocs build)	✅	✅

The env var is set at the step level (not job level) so it is scoped precisely:

# python-test.yml Check if dirty step (newly added)
- name: Check if dirty (mkdocs)
  env:
    NO_MKDOCS_2_WARNING: '1'
  run: |
    make check-for-changes

---

Files changed

File	Change
pyproject.toml	Pin mkdocs>=1.6.0,<2.0.0; pin mkdocs-material>=9.0.0,<10.0.0
.github/workflows/python-test.yml	Add NO_MKDOCS_2_WARNING: '1' to Validate website content and Check if dirty steps (Check if dirty is new not in #2131)
.github/workflows/python-push.yml	Add NO_MKDOCS_2_WARNING: '1' to Validate website content step
.github/workflows/docs-update.yml	Add NO_MKDOCS_2_WARNING: '1' to Create release step

---

Testing

• This fix is purely declarative (dependency pins + CI env var). No Python logic changes.
• The CI jobs test, bdist, and deploy-docs will validate the build against the pinned dependency set.
• Once the Material for MkDocs project and other plugins officially support MkDocs 2.0, these upper bounds can be widened and this NO_MKDOCS_2_WARNING guard can be removed.

---

Checklist

• Pins mkdocs<2.0.0 to prevent accidental MkDocs 2.0 installation
• Pins mkdocs-material<10.0.0 to close the transitive-dependency loophole
• Suppresses MkDocs 1.x deprecation warning in all four CI steps that invoke mkdocs (directly or via mike)
• No runtime code changes zero risk of behavioral regression
• Conventional commit message: fix: pin mkdocs<2.0 and mkdocs-material<10, add NO_MKDOCS_2_WARNING to all CI doc steps
  closes Upgrade trestle to use MkDocs 2.0 #2104

[Acuspeedster]

@vikas-agarwal76
@degenaro
@butler54

[github-actions]

This pull request has been automatically marked as stale because it has not had activity within 90 days. It will be automatically closed if no further activity occurs within 30 days.