fix: constrain documentation dependencies to fix project pipeline - #122
Merged
Merged
Conversation
mkdocs-material 9.6.0 deprecated the `tags` plugin's `tags_file` option, which the template's mkdocs.yml still sets. Under `mkdocs build --strict` the resulting configuration warning aborts the docs build, so no release in the previous `>=9.7.5,<10` range can build the docs. This commit pins mkdocs-material to `>=9.5.50,<9.6`, the latest line that still accepts `tags_file` without warning.
`mkdocs.yml` configures the Python handler with `setup_commands`, which boots Django so docstrings can be collected from the importable source tree. That option only exists in the legacy, pytkdocs-based handler. The modern griffe handler that `mkdocstrings` pulls in by default rejects it. The bare `mkdocstrings` dependency also shipped no handler at all, so the build failed even earlier. This commit depends on `mkdocstrings[python-legacy]`, installing the legacy handler that understands `setup_commands`.
bardiharborow
added
bug
bardiharborow
marked this pull request as ready for review
June 24, 2026 12:43
a-musing-moose
approved these changes
Jun 24, 2026
a-musing-moose
left a comment
a-musing-moose
left a comment
Contributor
There was a problem hiding this comment.
Thanks Bardi - pinning if the right option here as the intent is to migrate to Zensical in the future.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR fixes two issues that were preventing the generated project's pipeline from passing:
tagsplugin'stags_fileoption, which the template's mkdocs.yml still sets. Undermkdocs build --strictthe resulting configuration warning aborts the docs build, so no release in the previous>=9.7.5,<10range can build the docs. This PR pins mkdocs-material to>=9.5.50,<9.6, the latest line that still acceptstags_filewithout warning.mkdocs.ymlconfigures the Python handler withsetup_commands, which boots Django so docstrings can be collected from the importable source tree. That option only exists in the legacy, pytkdocs-based handler. The modern griffe handler thatmkdocstringspulls in by default rejects it. The baremkdocstringsdependency also shipped no handler at all, so the build failed even earlier. This PR depends onmkdocstrings[python-legacy], installing the legacy handler that understandssetup_commands.I chose to pin the dependancies back rather than fix forward because we are considered replacing this system in #104, and because this is a pre-factor for #120.
This PR has been verified locally.