-
-
Notifications
You must be signed in to change notification settings - Fork 3.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support mkdocs 1.6.0
#7076
Comments
I ran into this issue this morning as well. This is specifically a problem with Upgrading the pip version to Recreation steps:Launch a new ubuntu 22.04 container:
Inside the container
Observe that pypa/pip#10851 occurs |
Thanks for noting. As said, any help is appreciated! |
Here you go. Don't need to credit me In here you need to perform this change: mkdocs-material/requirements.txt Line 24 in 5f40a53
-mkdocs~=1.5.3
+mkdocs>=1.5.3 |
For more background regarding reasoning (though that comment of mine is on an unrelated project) see Guts/mkdocs-rss-plugin#137 (comment) |
Thanks @oprypin, I'm aware how to update the MkDocs dependency. I'm just concerned it breaks something in the community edition or in Insiders, which is why we need to test everything before considering the upgrade safe Thus, if somebody has some time, testing MkDocs 1.6 against the community edition and Insiders is appreciated ✌️ If nobody is up for it, I'll try to find some time on the weekend. |
I tested all changes against 40 websites using mkdocs-material (and I don't have access to mkdocs-material-insiders), on a continuous basis. Is that enough? |
Sounds good As said, I'll try to find some time by the end of the week 💪 |
|
There's no diff in HTML in almost all cases so there's no need to even visually inspect it. There were diffs on this one site but I think the site's build includes randomization or something https://github.com/mkdocs/regressions/actions/runs/8638288330/job/23682412864 |
@oprypin |
I've checked our changelog and it was 2.0 and 3.0. 3.0 turns out be updating to MkDocs 1.0, so all good, long ago, so my memories were probably faded 😅 Regardless, the title handling that came with MkDocs 1.5 was broken for almost a year now, which is why I decided to limit versions to be more careful.
Jup, that is expected. As I've outlined in mkdocs/mkdocs#3636 (comment), my opinion is that themes and plugins should define with which version of MkDocs they are compatible. In our installation guide, we do not list in any place that you should install |
@alexvoss jup, the generated files API looks very promising! We can probably get rid of a few dozens lines of code in our plugins, specifically the blog plugin! |
Again, |
Again, it is only a temporary solution, until we found the time to test it with the entirety of our code base. Please be patient, we will handle this in the coming days. Thank you for your understanding |
Did you run this? What is expected? Is it really expected to you that pip does the following: Download mkdocs_material-9.5.17. Is it compatible with MkDocs 1.6? No Is it expected that, until the end of days, users will occasionally install mkdocs_material-9.5.2 because that was the last version that supported all versions of MkDocs? |
No, I did not, because it's nothing we recommend doing on our documentation:
Nope, as said in #7076 (comment), we're working on it! |
Additionally:
I agree that the output is rather ugly. That's something that should be reported upstream to the maintainers of pip. |
FYI, I pinned the issue so that users coming to our issue tracker see immediately that we're working on it |
As a sponsor of this library, I would be disappointed if the maintainer had given in to the pressure above to YOLO every release instead of testing/verifying it. Thank you for the good tradecraft exhibited. |
There is a workaround that could be used to make everyone happy: add a The risk-afraid ones can install One extra benefit is that doing this could allow keeping the CI/CD pipelines green, as no new dependencies will randomly break the. Still, I recommend keeping one 'devel' pipeline that is not using the constraints, one that would report on upcoming breakages. |
Users should simply lock dependencies themselves by running pip-compile or equivalent. That's the only way to protect CI and to avoid any unexpected changes. |
I'm coming from the rather straight forward dependency management in Node.js (which, yes, also has its problems), and I really have trouble with Python's dependency management. I do not expect users of Material for MkDocs to be experts in how to use pip, since many of them are non-technical, so our goal should be to make it as simple as possible. IMHO, offering more installation options like |
I don't think that recommendation is good because using
In case you haven't come across it yet, there's a (IMO) fantastic article on Python dependency management with regard to upper bounds: https://iscinumpy.dev/post/bound-version-constraints In contrast to package managers in Node.js, which can install multiple versions of the same library at the same time, Python uses global dependency resolution, so upper bounds can render the dependency tree unresolvable pretty quickly. So, in most cases no upper bounds should be used, temporary upper bounds until a proper fix is available are okay, and upper bounds can always be introduced in userland. |
So we should remove Once we upgraded, my suggestion would be to change the requirement to:
This would get us all new releases except for the next major release. Setting it to 1.5.3 was just a temporary safety net. Please also understand that we have many, many non-technical users that have no idea how Python version managment works, so essentially, we're trying to make it simpler for them by providing this safety net. |
In my view, Material for MkDocs is an application and not a library, as it is not consumed by other Python packages. MkDocs on the other hand is an application and a library, as it exports utilities that are used by plugins, etc. Material for MkDocs is essentially a There are no Python packages that have Material for MkDocs as a dependency. Edit: ignore my words, yes, I'm mistaken, it's a root and not a leaf dependency (got it twisted in my head). Regardless the choice of the wrong word, the rest remains: IMHO, not a library, which is why we should be cautious and prudent about our upstream dependencies. |
Fair, maybe it's a rare example of something that doesn't exactly fit into either of the two cases |
I agree, Material for MkDocs is an application and not a library. It should always install on its own successfully, and it should be validated to work with whatever version of MkDocs it "ships with" and not "maybe it will work with whatever is the latest MkDocs, maybe it will have subtle bugs, maybe it will have severe errors". In other words, exactly what's happening now. |
Let's agree that we disagree here, i.e., have conflicting views, which is perfectly fine and good to talk about As said, I recommend we go back to |
I just fixed the most apparent error that we discovered in Insiders. Let's short-circuit this discussion by getting to work. Here are two PRs, one for the community edition and one for Insiders! Let's test it for a few days and if we think we caught all problems, release it 🚀 As discussed, I set the version range to Community edition
Insiders
|
Interesting discussion. Can't help but give my 2 cents 😄 I agree that Material for MkDocs is kinda in between applications and libraries. Application because for end-users, not consumed by other Python packages. Library because it still blends with all other dependencies of any given project using it, in the same resolution algorithm used to resolve these other dependencies. In my experience though, as someone who glues a lot of Python "tools" together, many projects that consider themselves applications (or CLI tools, or any other name that doesn't imply "library") are actually libraries. In my experience again, all Python packages are libraries. I'll go further: all packages are libraries, whatever the ecosystem. If you're in the ecosystem, you (willingly or not) play by its (resolution) rules, and you should be a kind fellow citizen. If you can depend on an "application", whether you consume it or not, then you can use it as a library. We should never underestimate the imaginative ways developers can consume or depend on something 😉 True applications are projects which are not packaged within this ecosystem. They are above it. True applications simply provide an install script, a requirements.txt file, a ZIP file, or whatever suits the devs of the application and their users, but they do not exist within the underlying ecosystem(s) (ecosystems can be layered). I see Material for MkDocs as a building block to build websites, not a final product: you install it alongside MkDocs core, as well as many other plugins, Markdown extensions, and various Python tooling to lint, test, build, deploy your docs. To me, Material for MkDocs is indeed a library 😛 Especially now that it provides many plugins that can be used independently of the theme itself. Don't get me wrong: I absolutely don't mind temporary pins or upper bounds: I sometimes use them myself, and they do the job perfectly when I want to prevent a known breakage while waiting for / working on a fix, or more generally waiting for / working on supporting the new version of the pinned/capped dependency. But yeah, the Python ecosystem suffers from this flat packages layout, and so pins and upper bounds are highly discouraged. I really recommend the article mentioned by @sisp: https://iscinumpy.dev/post/bound-version-constraints, it explains it well. |
As for the demographics of Material for MkDocs, I don't have anything smart to say. Installing Material for MkDocs is easy, but understanding that there's a compatibility issue, understanding where to search for ways to resolve it, and understanding the suggested ways to resolve it (if there are any) is definitely not as easy. So I understand the need to simplify this for your users 🙂 Would be interesting to know the percentage of non-technical users that manage their Python dependencies themselves vs. those who rely on technical peers for that. But that's for another day 😄 |
I'm not sure if this is related, but I'm getting this error in my mkdocs workflow: Successfully built paginate
ERROR: Exception:
Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/pip/_internal/cli/base_command.py", line 165, in exc_logging_wrapper
status = run_func(*args)
File "/usr/lib/python3/dist-packages/pip/_internal/cli/req_command.py", line 205, in wrapper
return func(self, options, args)
File "/usr/lib/python3/dist-packages/pip/_internal/commands/install.py", line 389, in run
to_install = resolver.get_installation_order(requirement_set)
File "/usr/lib/python3/dist-packages/pip/_internal/resolution/resolvelib/resolver.py", line 188, in get_installation_order
weights = get_topological_weights(
File "/usr/lib/python3/dist-packages/pip/_internal/resolution/resolvelib/resolver.py", line 2[76](https://github.com/nicfv/Me/actions/runs/8807702921/job/24175351696#step:2:77), in get_topological_weights
assert len(weights) == expected_node_count
AssertionError
Error: Process completed with exit code 2. But it seems like mkdocs 1.6.0 and mkdocs-material 9.5.18 both installed successfully. |
Yes it is related, see #7076 (comment) mkdocs/mkdocs#3477 (comment) |
@nicfv you can already test a fix, as noted in #7076 (comment) – we'll release it in the coming days
|
Our testing shows that we consider it quite safe to upgrade to MkDocs 1.6 🎉 If we hit problems, we'll fix them on the way – as always. The new anchor validation functionality is very useful, and allowed me to fix tons of anchor links in 2585b82 that went stale due to several restructures. Some of the warnings cannot be fixed, because anchors that do exist are not picked up by MkDocs, but that's no problem for us, we'll just live with that. |
Released as part of 9.5.19. 4 days from MkDocs' release of 1.6 to us adopting it – not bad 😎 If you find any issues that are related to the MkDocs version bump, please create a new issue here or upstream, depending on what the cause is. If unsure, please create a discussion first. This issue can be considered resolved now. |
For future reference, all of these really tight dependencies are making it really hard to upgrade packages independently. It's not clear to me there's a high value in doing this. For example, I'm still blocked because mkdocs-techdocs-core requires a very specific version of mkdocs-material: Obviously that's it's own problem (using exact dependencies). But anyways, by changing your requirements to be mkdocs ~1.6, you're saying that mkdocs-material is no longer compatible with 1.5. This isn't true and is unnecessarily restricting the allowable solve space. Instead, it would be better to be Since you all are really insistent on not allowing future versions of mkdocs without a manual step, you could do |
@intentionally-left-nil I understand your concerns. However, while the community edition should still be compatible with 1.5, Insiders is definitely not, and we try to keep it synchronized to ease interop and switching back and forth for our sponsors. Our goal is to stay up-to-date with the latest version of MkDocs, as it's currently our most critical dependency. Additionally |
* There was a bit of discussion upstream about the pinning but that is resolved squidfunk/mkdocs-material#7076
* There was a bit of discussion upstream about the pinning but that is resolved squidfunk/mkdocs-material#7076
Again, I really recommend reading https://iscinumpy.dev/post/bound-version-constraints/ and https://hynek.me/articles/semver-will-not-save-you/. For Python libraries, use only lower bounds whenever possible; for apps (root of the dependency tree), use pins (lock file or even manifest pins + lock file). Clearly, @pawamoy also summarized it very well: #7076 (comment) |
@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. |
Note
Edit by @squidfunk: fix available, please check if your documentation builds successfully, see #7076 (comment)
Context
When I try to install
mkdocs 1.6.0
I get a warning frompip
thatmkdocs-material
only supports a1.5.x
version ofmkdocs
.Copy/pasting a relevant comment from @squidfunk:
Source for comment: renovatebot/renovatebot.github.io#439 (comment)
I don't feel confident to work on the code on
mkdocs-material
. I can at least make an issue for this work, so you can track it. Maybe someone from the community can help you work on this feature.Description
Update Material for MkDocs so it works with
1.6.0.
ofmkdocs
.Related links
Read the
mkdocs
1.6.0 changelog to check for important changes.mkdocs 1.6.0
also has a newenabled
setting for all plugins. I don't know if/how this affects Material for MkDocs. Maybe you should default toenabled: false
on some parts, or explictlyenabled: true
on others...Use Cases
MkDocs
1.6.0
has new validation options:It's a good idea to validate the links before publishing the docs, that way readers don't suddenly end up with a broken link.
Visuals
No response
Before submitting
The text was updated successfully, but these errors were encountered: