Enabling This Incorrectly Applies a Substitution to All Types in API Docs

[alexdlaird]

I enabled this extension for a single variable on my project, pyngrok_version. All I changed was adding the extension, adding this to conf.py:

rst_prolog = """
.. |pyngrok_version| replace:: {pyngrok_version}
""".format(pyngrok_version=version)

And then in my troubleshooting.rst file, I have this line now where the substitution should occur:

.. code-block:: shell
    :substitutions:

    ...

    PYNGROK VERSION:
       |pyngrok_version|

And that works great, the version 7.1.5 now appears there and will auto-update! Unfortunately, with no other configuration change (here is the commit), my API docs all look like this now:

All types now appear to also have this substitution applied. They used to look like like:

I disabled this on my main branch so latest would be stable again, so you can see how the API docs are supposed to look here. Then I enabled a hidden branch on ReadTheDocs so you can see them broken here.

[adamtheturtle]

Thank you @alexdlaird for the detailed report.

I don't think that this is a problem with sphinx-substitution-extensions, but instead I think that it is a problem with sphinx_autodoc_typehints.

If I take your project at main, and then add only:

# end of conf.py
rst_prolog = """
.. |something| replace:: 7.1.5
"""

You will see that the error you posted occurs.

[alexdlaird]

Great find. I'll try some things out without your extension enabled and may open a bug for them over there as well, as it doesn't just seem like the extensions are incompatible with each other, it seems like their typedoc hints are causing an overly-greedy replacement.

A defining / useful aspect of that extension is that it substitutes unions |, the same operator you look for, in to Optional[type], so that's probably where it breaks.

[adamtheturtle]

I'll close this issue now then, and I'm open to more issues. Good luck!

[alexdlaird]

This issue over there references the same problem (manifest differently): tox-dev/sphinx-autodoc-typehints#425

It appears this PR of theirs broke it: tox-dev/sphinx-autodoc-typehints#422

Solution (until they fix it), pin the version back, where it works fine with or without your library:

sphinx_autodoc_typehints==1.25.2