search

jimporter / mike

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

Can `set-default` use symlinks? #106

Closed jimporter closed 10 months ago

jimporter commented 2 years ago

After #92 is closed, symlinks will be the default way of representing aliases. It would be nice if the set-default redirect could use this too, but it will probably take a bit of testing at minimum to verify that it doesn't mess up relative paths in the HTML.

ofek commented 10 months ago

As I mentioned in https://github.com/jimporter/mike/issues/82#issuecomment-1773646208 I think if we care about Windows compatibility that we should not use symbolic links:

By default, only administrators are able to use those https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links#default-values

See also this comment from a CPython core developer at Microsoft regarding a proposal to use symlinks in a packaging standard https://discuss.python.org/t/discuss-pep-662-editable-installs-via-virtual-wheels/9071/97

Those tests fail on my machine, and I have the highest privileges (I'm guessing I never enabled the option):

image

jimporter commented 10 months ago

As I mentioned in #82 (comment) I think if we care about Windows compatibility that we should not use symbolic links:

Since the point of mike is to host documentation on Github via the gh-pages branch, I don't think it matters much if a local machine with a Git clone can't use symlinks. It's pretty rare that you'd need to check out the gh-pages branch locally.

Those tests fail on my machine, and I have the highest privileges (I'm guessing I never enabled the option):

In all likelihood, that code actually works, but you're just not getting actual symlinks in the checkout since you don't have the right permissions (see core.symlinks). Notably, the tests fail after git checkout gh-pages finishes successfully. It might be possible to tweak the tests to pass in that case too, but in practice I think we can trust that Git does the right thing here.

What matters for this issue is mainly figuring out how Github Pages will handle symlinking index.html to some-version/index.html. For example, do relative paths, images, etc still work correctly?

jimporter commented 10 months ago

I finally had time to test this out and the answer to the title is no. HTML redirects are necessary for mike set-default.