jimporter / mike

Manage multiple versions of your MkDocs-powered documentation via Git
BSD 3-Clause "New" or "Revised" License
551 stars 47 forks source link

Deprecation warning "Path 'js\version-select.js' uses OS-specific separator '\'" on Windows 10 #226

Open alexzhornyak opened 3 months ago

alexzhornyak commented 3 months ago

Summary

Deprecation warning "Path 'js\version-select.js' uses OS-specific separator '\'" on Windows 10

Configuration and Logs

When I am trying to build repository I see deprecation warning messages in logs:

WARNING -  Path 'js\version-select.js' uses OS-specific separator '\'. That will be unsupported in a future release. Please change it to '/'.
WARNING -  Path 'css\version-select.css' uses OS-specific separator '\'. That will be unsupported in a future release. Please change it to '/'.

Steps to Reproduce

  1. Command mike deploy latest
jimporter commented 3 months ago

By the warning style, this looks like an issue in MkDocs. MkDocs' documentation doesn't seem to specify what path styles are acceptable, which would lead me to believe that backslashes are allowed in filenames in mkdocs.yml. So this seems like a bug in MkDocs: either backslashes are allowed, in which case the warning should be suppressed/avoided, or they're not allowed and the documentation should be clearer about this. (In the latter case, mike would need to account for that change, but probably better to wait and see the response from the MkDocs maintainers.)

alexzhornyak commented 3 months ago

https://github.com/mkdocs/mkdocs/issues/439

It seems like there is somewhere in MkDocs documentation that backslashes are not recommended. I didn't dive deep into their docs, but after reading this thread, it seems like you should not use them

jimporter commented 3 months ago

mkdocs/mkdocs#439

The last comment in that issue includes this:

And for those Windows users who ignore the documentation and don't use forward slashes in their config, it will still work for them as long as they stay on Windows.

I think the discussion in that issue indicates that Windows-style paths are explicitly supported in MkDocs, so long as they're only used on Windows systems. Since these backslashes should only be in a temporary file generated by mike during the build process, that file will always stay on Windows. (A Linux user running mike would see forward slashes in the temporary file.) Therefore, I think mike is simply using a supported feature in MkDocs. That makes me think this is just a bug with MkDocs (they're probably using Python Path objects and Python is complaining about this now?).

alexzhornyak commented 3 months ago

The phrase "who ignore the documentation" make me interested to find where is it described but quick search didn't help me to find it.

jimporter commented 3 months ago

Yeah, I tried searching in some of the likely parts of the MkDocs documentation where this would be mentioned, and I couldn't find anything. If MkDocs wants to forbid backslashes in paths, I don't really mind, though this ultimately arises because mike is making an effort to be safe and using the platform's path separator, rather than hardcoding forward-slash.

(I have a suspicion that this might really be a Python standard library bug, though I haven't looked into the stdlib code: if Python Path objects are trying to forbid the use of backslash, then this would likely cause a lot of problems interacting with libraries. Suppose some code uses os.path.join, which uses backslash on Windows, and then sends that string to some third-party library that converts string paths to Path objects - maybe the developers of that library just like Path objects more. If that conversion doesn't accept backslashed paths, then it means that you can't use os.path.join reliably anymore!)

alexzhornyak commented 3 months ago

Ok, thank you for your support. Mike is great tool, hope that it will work long long time. I agree that is better to use standard path libraries, etc. So leave as is. And this issue will be like explanation for other users that will face with such warnings

jimporter commented 3 months ago

Yeah, again it does feel like something should be done somewhere about this, but I'd have to spend some more time digging through exactly where this is cropping up. This is one of those warnings where - while it's easy to make it go away - makes me nervous that there's some bigger issue lurking just underneath...