Intersphinx catalog to link to the documentation

[gaborbernat]

Any way we can generate an Intersphinx catalog one can use to automatically link to the documentation?

Something like this would work to patch it:

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)

though unsure how to emphasize the URI 🤔

[tomchristie]

Discussion at #3091

Yep... does anyone want to look into switching our code docstring support to mkdocstrings?

[Stealthii]

Odd that I was just about to raise this very issue after stumbling through @gaborbernat's latest docs, as I'm trying to link documentation for a downstream module of httpx.

An example of mkdocstrings own configuration can be seen here:
https://github.com/mkdocstrings/mkdocstrings/blob/0.26.2/mkdocs.yml#L136-L163

WIP changes at feature/mkdocstrings. Some concessions will need to be made between matching in with current mkautodocs format, and the options exposed by mkdocstrings. Some improvements to actual docstrings within the Python code (part tracked by #3355) should be made to improve the generated docs.

[pawamoy]

@Stealthii let me know if you open a PR, I'll have some comments and suggestions 🙂