Fixing the issue #754

[tharun-mk]

Fix for Issue #754 (Windows docs build warning)

Description:
This PR resolves the Sphinx build warning caused by the case-insensitive file collision on Windows between the Device class and the device object in brian2.devices.device.

I had Added an autodoc-skip-member hook to docs_sphinx/conf.py to explicitly skip the lowercase device instance when Sphinx generates the module documentation.

Fixes #754

[mstimberg]

Hi @tharun-mk. Thanks for the PR. I am a bit confused, though: this seems to only change some whitespace in the file and does not address the issue?

[xBelisarius]

hey @mstimberg, while i do not know if the changes here affect the issue in #754, i did notice some warnings are caused because sphinx is picky about white spaces in source files, for example when dealing with tables.
My draft PR includes one such changes i noticed and added white spaces, which fixed the error. #1788

I wonder if there is a tool or if i should implement something that automatically fixes white space formatting in the doc source files. Just food for thought though.

[tharun-mk]

@mstimberg sorry sir i have accidentally made pr that has no changes. now i have made the real pr with actual changes required I implemented an O(1) dictionary cache hook in conf.py. It dynamically scans the module once, caches the members, and safely skips any lowercase member that collides with any other case variation (Capitalized, UPPERCASE, CamelCase, etc.) in the exact same module. This permanently prevents this class of Windows filesystem bugs without sacrificing CI build speeds. Let me know if this implementation looks good to you.

[mstimberg]

Hi @tharun-mk, no worries about the empty commit, I figured it was something like this.

I didn't yet look into your changes, but do I understand correctly that your solution means skipping members that can lead to problem on Windows? If this is the case, I'm not sure that it is the best solution, since it means that those members disappear from the documentation on the other OSs (including our online documentation). My ideal solution would be to have all members documented on all OSs, otherwise I think the current situation (with a warning on Windows) is actually better than not documenting the problematic members on any OS.

[tharun-mk]

@mstimberg Sir, If I use an if statement with sys module's platform to check whether it was windows or other os if it was windows the code executed or else it returns the skip

[mstimberg]

Hi @tharun-mk. Thanks for the update. Could you please explain a bit the logic behind your check and how you tested it? Just from looking at the code, I think it would still both include Device and device.

[tharun-mk]

Hi @mstimberg,
I am developing on Ubuntu, so I was not able to natively test the HTML file-generation collision on a Windows environment. I relied purely on the Python logic rather than a localized Windows build test.
Regarding the logic: My intent was that if name is lowercase (e.g., device), it triggers the check. The cache maps device to a set of {'device', 'Device'}. Since the length is > 1, it returns True and skips the lowercase object. When Sphinx passes the uppercase Device, name.islower() evaluates to False, so it bypasses the check and gets included.
However, stepping back, I realize I completely missed the core point of your previous feedback. You explicitly stated that your ideal solution is to have all members documented on all OSs, and that a warning is preferable to missing documentation. My if sys.platform == 'win32' check missed the mark because it still results in Windows users losing the documentation for device just to suppress a terminal warning.

I believe the true fix would involve modifying the custom Sphinx filename router inside generate_reference.py to safely handle case-insensitive file systems without breaking the cross-referencing URLs. However, I haven't done a deep dive into generate_reference.py for this specific fix yet, as my primary focus right now is analyzing the architecture for the GSoC Project #2 proposal (Sphinx-Gallery & Napoleon).
Given this, would you prefer I simply close this PR since the current approach is incorrect? I am happy to close it so we keep the documentation intact, or I can pivot to investigating the filename router if you think it's worth the immediate effort.

[mstimberg]

Hi again. My question about testing wasn't so much about testing it on Windows, but about testing the logic itself, e.g. by logging what it would do. I'm still not quite sure whether the logic is correct, but I wasn't able to test it either. If I add raise Exception() to the first line of skip_case_collisions, the documentation still gets built, so I think that this hook is never actually triggered here… I think you are correct that fixing generate_reference would be the correct thing to do here. As part of the GSoC project, probably replacing it by something like https://sphinx-immaterial.readthedocs.io/en/latest/apidoc/python/apigen.html (which seems to deal with the case-insensitive file issue) would probably be a better long-term solution. I therefore agree to rather close this issue for now.