search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.19k stars 2.03k forks source link

Type annotation reference unclickable #12496

Open oddbookworm opened 1 week ago

oddbookworm commented 1 week ago

Describe the bug

In a very rare case, when I try to click on a reference in a type annotation, I get the following behavior:

https://github.com/sphinx-doc/sphinx/assets/49015102/8e5aeb28-ef51-40d3-ae83-c4ad19606431

I stumbled upon this while playing around with fixing a multiple target warning because we have two classes with the same name (it's just that we're migrating from the old location to the new location and the one that sphinx links to is the deprecated version). I fixed that by qualifying specifically which version of the class I wanted to reference, but then this happens

How to Reproduce

Unfortunately, I don't have a standalone reproducer, so I'm just going to have to give a repo and stuff. I'm linking to a branch on my fork that has the fix I mentioned above. If you clone the upstream or any other branch, it'll just show the warning

git clone https://github.com/oddbookworm/pygame-ce
git checkout sphinx-warning
cd pygame-ce
python -m venv venv
# activate it, depending on OS
pip install sphinx
python buildconfig\make_docs.py full_generation
python -m docs
# navigate to ${repo_dir}/docs/generated/ref/display.html#pygame.display.message_box
    # i.e. if your browser opens at file:///C:/Users/andre/Projects/pygame-ce/docs/generated/index.html, replace `index.html` with `ref/display.html#pygame.display.message_box`
Try to hover over the `pygame.Window` annotation in the param list

edited since initial post to indicate the actual process for getting to the branch needed

Environment Information

Platform:              win32; (Windows-10-10.0.22631-SP0)
Python version:        3.11.5 (tags/v3.11.5:cce6ba9, Aug 24 2023, 14:38:34) [MSC v.1936 64 bit (AMD64)])
Python implementation: CPython
Sphinx version:        7.3.7
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

No response

Additional context

I tried on 3 browsers: Chrome 126.0.6478.127 Edge 126.0.2592.81 Firefox 127.0.2

I was able to reproduce it on Chrome and Edge, but not Firefox. Of note is that Ff didn't show the tooltip about the class that is demo'd in the video

electric-coder commented 6 days ago

I stumbled upon this while playing around with fixing a multiple target warning

If you have underlying errors there's no guarantee those won't cause strange behavior. Fixing the multiple target error should fix that bug. I can't recall seeing any mention of the error you're showing.

Unfortunately, I don't have a standalone reproducer

Not all is bad, at least you have a video! But you'd be surprised how many devs show up with a: "here repo - you fix!" attitude demanding someone fix their supposed "bug" when actually it's a basic error of their making. Anyway, call me an old timer but I don't clone repos. (And as all good old timers I'm grumpy and lazy on Sundays :D )