RST link with replace not handled properly

[fmigneault]

Summary

There are 3 use cases where RST replace:: directive are not handled properly with links.

All below examples use the following source for corresponding contents:

• GitHub: https://github.com/crim-ca/weaver/tree/master
• ReadTheDocs: https://pavics-weaver.readthedocs.io/

Case 1 - Embedded link in replace

Below is a replacement directive, which contains a link:
(source: https://github.com/crim-ca/weaver/blob/ee70c772dd860fdeb569bf1f87b946c76809e08a/README.rst?plain=1#L331-L332)

|ogc-api-proc-part2|

.. |ogc-api-proc-part2| replace:: `OGC API - Processes - Part 2: Deploy, Replace, Undeploy`_ (DRU) extension
.. _`OGC API - Processes - Part 2: Deploy, Replace, Undeploy`: https://github.com/opengeospatial/ogcapi-processes/tree/master/extensions/deploy_replace_undeploy

When rendered by GitHub, a link is generated, but it does not resolve to the right location:
https://github.com/crim-ca/weaver?tab=readme-ov-file#extra-details--sponsors

The same link rendered by Sphinx and posted on ReadTheDocs is valid:
https://pavics-weaver.readthedocs.io/en/latest/#extra-details-sponsors

Case 2 - Link applied on replaced content

(source: https://github.com/crim-ca/weaver/blob/ee70c772dd860fdeb569bf1f87b946c76809e08a/README.rst?plain=1#L327-L328)

|ogc-eo-apps-pilot-er|_

.. |ogc-eo-apps-pilot-er| replace:: OGC Earth Observation Applications Pilot: CRIM Engineering Report
.. _ogc-eo-apps-pilot-er: http://docs.opengeospatial.org/per/20-045.html

Link not rendered on GitHub:

Works on ReadTheDocs:

Case 3 - Mix of both previous link/replace in a nested fashion

(source: https://github.com/crim-ca/weaver/blob/ee70c772dd860fdeb569bf1f87b946c76809e08a/README.rst?plain=1#L308-L310)

|ogc-proc-long|

.. |ogc-api-proc| replace:: `OGC API - Processes`
.. _ogc-api-proc: https://github.com/opengeospatial/ogcapi-processes
.. |ogc-proc-long| replace:: |ogc-api-proc|_ (WPS-REST bindings)

Link not rendered on GitHub:

Works on ReadTheDocs:

[TDKorn]

Same here (see https://github.com/orgs/community/discussions/114840)

[mentalisttraceur]

By the way, in reST this is the only way to have formatting in links.

The above examples are all prose formatting, but this also breaks developer-centric stuff, like links to function/class/package documentation which mark the name as code.