Hi. May I kindly ping on this? If you anticipate that reviewing this PR won't happen in the near future, that's ofc understandable - would just be convenient to know since I have a PR open that could proceed differently in that case :)

hey there -

yes sorry, i have lots and lots going on and this particular PR, I'd have to spend time with to understand the implications. in particular if it's going to change when/if/how errors or warnings are getting reported, that may or may not be trouble. as you mention, we dont know how it will interact with nitpick_ignore, and I dont have a good understanding of sphinx's various "nitpicky" modes in any case they seem to have changed from what they were a long time ago.

might it be simpler for sphinx-paramlinks itself to just emit a warning, but otherwise not change in any behavioral sense ?

No worries.

I understand your concerns and your message lead me to have another look at the internals of sphinx. Indeed I had misunderstood the situation a bit. The flow is as follows:

1. sphinx encounters a reference that wasn't resolved
2. pass it to the missing-reference handlers (lookup_params in case of sphinx-pl) - if one of them returns a node, the reference is maked as resolved.
3. if instead all handlers returned None:
4. first check if it's supposed to be ignored by the nitpick_ignore(_regex) settings. this works with the node["reftarget"], for which sphinx-pl inserts the _sphinx_paramlinks_ marker
5. if not, forward it to the warn-missing-reference handlers. if none of them returns True, issue a default warning.

So by returning None from lookup_params, we'd already have proper nitpick support - with the caveat that one needs to ignore ('py:paramref', '_sphinx_paramlinks_current_offset') rather than ('py:paramref', 'current_offset') and similar for the regex.

Implementing a handler for warn-missing-reference or issuing the warning directly in lookup_params would have the upside that the proper name can be shown in the log entry and it would allow to apply adjusted handling for nitpicky settings. The downside would be additional implementation effort, especially if the nitpicky settings should be respected.

The punchlin(s) is

• by returning None from lookup_params, nitpick_ignore is applied to sphinx-pl out of the box
• to use it, one either needs custom tooling in sphinx-pl or needs to remember the _sphinx_paramlinks_ marker for the nitpicky_ignore settings.

Personally, I'd be fine without custom tooling and just documenting the limitation.

looks like a doc fix was made upstream so that I dont have to try to understand waht this is about, thanks!

Hi. Unfortunately sphinx-doc/sphinx#10119 does not actually resolve this PR, but is just a spin-off documentation fix that I noticed while working on this one. What this PR addresses is the 2nd point in my comment #14 (comment). What sphinx-doc/sphinx#10119 does is clarify point 4 inside the sphinx docs.