search

twisted / pydoctor

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

pydoctor crashes on Windows when trying to symlink to a nonexistent file: 'index.html' #808

Closed rocketengineer1982 closed 1 month ago

rocketengineer1982 commented 1 month ago

Trying to generate documentation of a single package using pydoctor results in [WinError 5] Access is denied: 'index.hmtl' -> 'package_name.html'

I'm running Python 3 on Windows 10 using Anaconda. I'm calling pydoctor from the command line using a batch script.

python -m pydoctor --project-name=package_name --make-html --html-output=%CD%\docs --project-base-dir=%CD% --docformat=plaintext %CD%\src\package_name

The traceback points to pydoctor\templatewriter\writer.py, line 111 in writeSummaryPages root_module_path.symlink_to('index.html')

The issue is that 'index.html' does not yet exist, so the symlink fails. 'index.html' is written when TemplateWriter._writeDocsFor is called by TemplateWriter.writeIndividualFiles. In driver.py the make function calls writeSummaryPages before calling writeIndividualFiles.

My quick "monkey patch" solution was to add a return after line 109 in writeSummaryPages in templatewriter\writer.py. 'packagename.html' is still not created, but all of the other html files are, including 'index.html'.

The creation of the symlink needs to be moved to after 'index.html' is created. My personal approach would be to add a new function to writer.py, perhaps called writeIndexLink, and move the code from lines 101-111 in writer.py to the new function. Then that new function would be called right after writeIndividualFiles is called on line 131 in driver.py.

tristanlatr commented 1 month ago

Thanks a lot the report. It has also been reported in #720. If you want to give it a try, I'de be glad to review your contribution. I believe your approach will work. Talk to you later,

tristanlatr commented 1 month ago

So weird the tests did not caught that though…

rocketengineer1982 commented 1 month ago

I think this may be a Windows-only bug and perhaps that is why tests did not catch it. Windows interprets creating a symlink as creating a shortcut, and cannot create a shortcut to a file that does not exist.

tristanlatr commented 1 month ago

All the tests are supposed to be run on windows as well. https://github.com/twisted/pydoctor/blob/0743773050e73d97963c695a785ed997f418b9b8/.github/workflows/unit.yaml#L26

rocketengineer1982 commented 1 month ago

I believe this issue can be closed. See https://github.com/twisted/pydoctor/pull/809#issuecomment-2227661145