search

twisted / pydoctor

This is pydoctor, an API documentation generator that works by static analysis.
https://pydoctor.readthedocs.io
Other
179 stars 48 forks source link

Symlink to index.html #720

Open buhtz opened 1 year ago

buhtz commented 1 year ago

It seems that pydoctor do create a a symlink (named with the package name) to index.html.

~I couldn't find the right place in code where this happens.~ I think it happens here.

I'm asking to modify this somehow. Maybe it could be a hard link instead of a symlink. Or it could be a regular html file with a redirect directive in it.

Symlinks do often confuse other software, e.g. nextCloud/ownCloud, some Backup software etc.

I can't think of a reason why it couldn't be a hardlink.

tristanlatr commented 1 year ago

I agree. It also confuses readthedocs (#696).

tristanlatr commented 1 year ago

Would you like to send a PR to fix it, @buhtz ?

buhtz commented 1 year ago

Would you like to send a PR to fix it, @buhtz ?

I can try. But it will take time. Please tell me if you like a hardlink or a redirecting html file.

tristanlatr commented 1 year ago

A hardlink will be ok I suppose.

tristanlatr commented 1 year ago

So using os.link()

jgarbers commented 11 months ago

I've been trying to build my docs on Windows, and creating the symlink also seems to require elevated privileges, since I get this error unless I run pydoctor as Administrator:

  File "C:\Users\jgarbers3\AppData\Local\Programs\Python\Python311\Lib\pathlib.py", line 1198, in symlink_to
    os.symlink(target, self, target_is_directory)
OSError: [WinError 1314] A required privilege is not held by the client: 'index.html' -> 'C:\\Users\\jgarbers3\\lab\\ev\\docs\\build\\html\\api\\ev.html'
tristanlatr commented 11 months ago

Thanks for the report, @jgarbers. You can try to fix the PR #722 if you want, I haven't allocated time to look at it yet.

tristanlatr commented 9 months ago

What about doing something like this: https://superuser.com/questions/560597/convert-symlinks-to-hard-links ? But in python, if a specific option is given, like --use-hard-links or something.

buhtz commented 6 months ago

I can also confirm the problem on Windows with missing user privileges.

tristanlatr commented 2 months ago

I believe a solution would be to build a mapping of links during the html writing. And after create those links with the appropriate strategy: either symbolic or hard links. This will be helpful as well for futures développements because we might have to create a lot of links to ensure no 404 are generated for a page name that correspond to a python module or class (because they might be moved during reparenting). See #739