Sphinx 8.1+: "Could not match transformation ..."

[cmarqu]

Starting with Sphinx 8.1 (I think), I am getting "Could not match transformation ..." warnings for otherwise nicely working links.

I have added more variables to the message logging to help debugging, but I haven't figured out the root cause yet (I also tried setting re.DEBUG but boy is this chatty...).

Sphinx 8.0 (https://www.sphinx-doc.org/en/master/changes/8.0.html):

name=Name(import_components=['cocotb', 'triggers', 'Timer'], code_str='Timer', lineno=63, end_lineno=63, context=<LinkContext.none: 'none'>, resolved_location='cocotb.triggers.Timer')
construct_name_pattern(name)='(?<!<span class="o">\\.</span>)()<span class="[a-z]+">@?Timer</span>(?!(<span class="o">\\.)|(</a>))'
selection='        <span class="k">await</span> <span class="n">Timer</span><span class="p">(</span><span class="mf">3.3</span><span class="p">,</span> <span class="s2">"us"</span><span class="p">)</span>'
/home/colin/tools/cocotb/docs/source/coroutines.rst: Matched transformation of `Timer` on source lines 3-3, source:
async def wait_10ns():
    cocotb.log.info("About to wait for 10 ns")
    await Timer(10, unit='ns')
    cocotb.log.info("Simulation time has advanced by 10 ns")

Sphinx 8.1 (https://www.sphinx-doc.org/en/master/changes/8.1.html):

name=Name(import_components=['cocotb', 'triggers', 'Timer'], code_str='Timer', lineno=63, end_lineno=63, context='none', resolved_location='cocotb.triggers.Timer')
construct_name_pattern(name)='(?<!<span class="o">\\.</span>)()<span class="[a-z]+">@?Timer</span>(?!(<span class="o">\\.)|(</a>))'
selection='        <span class="k">await</span> <a class="sphinx-codeautolink-a" href="library_reference.html#cocotb.triggers.Timer" title="cocotb.triggers.Timer"><span class="n">Timer</span></a><span class="p">(</span><span class="mf">3.3</span><span class="p">,</span> <span class="s2">"us"</span><span class="p">)</span>' [codeautolink.match_name]�[39;49;00m
�[91m/home/colin/tools/cocotb/docs/source/coroutines.rst: WARNING: Could not match transformation of `Timer` on source lines 3-3, source:
async def wait_10ns():
    cocotb.log.info("About to wait for 10 ns")
    await Timer(10, unit='ns')
    cocotb.log.info("Simulation time has advanced by 10 ns")

I suppose CI of sphinx-codeautolink should run every once in a while (even without changes in its own codebase) and check the latest releases of tools to find problems like this.

[felix-hilden]

Hi! Thanks for the report 👌🏿

Could you also make a minimal complete example of this? Or does this happen to any "await something"? Is the timer import in a preface?

I'm not sure about the Sphinx version thing, but the error and the prints suggest that the Timer was already linked once and for some reason we're trying to do it again.

[felix-hilden]

I added scheduled tests in #193 and tried to reproduced this locally with just "await something()". That didn't reproduce the issue with Sphinx 8.2. I think I'll need more information on the specific issue. How is "Timer" defined? How is it imported in the example? Did you determine an exact sphinx version where this stopped working and does it still malfunction with 8.2?

[cmarqu]

Thanks for looking into it, I will try to provide more Information soon.
The project in question is https://docs.cocotb.org/en/development/, https://github.com/cocotb/cocotb

[cmarqu]

I have just tried to investigate more, and can not trigger the behavior again.
Case closed for now :)

[felix-hilden]

Alright, thanks!