Static intersphinx mappings

[gaborbernat]

Is it possible to statically links some objects? E.g. some projects to not use Sphinx, and would still ike to link to it, for example for httpx.AsyncClient to https://www.python-httpx.org/api/#asyncclient?

[SilverRainZ]

sphinx.ext.extlinks may helps:

extensions.append('sphinx.ext.extlinks')
extlinks = {
    'httpx': ('https://www.python-httpx.org/api#%s', 'httpx.%s'),
}

:httpx:`AsyncClient` will be rendered to httpx.AsyncClient and targets to https://www.python-httpx.org/api/#AsyncClient.

But note that extlink wont do reslove&check like intersphinx it just generates a link according to your config.

[gaborbernat]

That only works if you write the doc manually, not if generated. For now I came up with:

def setup(app: Sphinx) -> None:  # noqa: D103
    class PatchedPythonDomain(PythonDomain):
        def resolve_xref(  # noqa: PLR0913, PLR0917
            self,
            env: BuildEnvironment,
            fromdocname: str,
            builder: Builder,
            type: str,  # noqa: A002
            target: str,
            node: pending_xref,
            contnode: Element,
        ) -> Element:
            if target in fixup:
                return reference("", text=target.split(".")[-1], refuri=fixup[target], internal=False)
            return super().resolve_xref(env, fromdocname, builder, type, target, node, contnode)

    fixup = {
        "httpx.AsyncClient": "https://www.python-httpx.org/api/#asyncclient",
        "starlette.applications.Starlette": "https://www.starlette.io/applications/#instantiating-the-application",
        "starlette.datastructures.Secret": "https://www.starlette.io/config/#secrets",
        "starlette.testclient.TestClient": "https://www.starlette.io/testclient/",
    }
    app.add_domain(PatchedPythonDomain, override=True)

which is not ideal, but works... perhaps we should have an intersphinx_static_map to hold this fixup mapping 😆 or can be a method that for an input target returns the URL should we want to make it more dynamic.