Could not find cross-reference target

[Ravencentric]

I have a pretty simple docstring like this:

class SomeAPI:
    def __init__(self, base_url: str = "https://someurl.com", client: Client | None = None) -> None:
        """

        Parameters
        ----------
        base_url : str, optional
            The base URL of used for constructing API queries.
        client : Client, optional
            An [httpx.Client][] instance used to make requests.
            
        [httpx.Client]: https://www.python-httpx.org/advanced/#client
        
        """

httpx does not provide objects.inv so we need to use normal links but the above fails:

WARNING -  griffe: Could not parse line '['httpx.Client']: https://www.python-httpx.org/advanced/#client'
WARNING -  mkdocs_autorefs: (package.MyClass.__init__) Could not find cross-reference target ''httpx.Client''

[Ravencentric]

Putting them on the same identation works:

class SomeAPI:
    def __init__(self, base_url: str = "https://someurl.com", client: Client | None = None) -> None:
        """

        Parameters
        ----------
        base_url : str, optional
            The base URL of used for constructing API queries.
        client : Client, optional
            An [httpx.Client][] instance used to make requests.

            [httpx.Client]: https://www.python-httpx.org/advanced/#client
        
        """

Note the empty line in between, seems to be necessary for VS code to pick it up as a hyperlink.

[pawamoy]

Yup, that's because docstrings are parsed into structured data and converted from Markdown to HTML in multiple steps. In the original example, the link (last line) is outside of the parameter description, so Python-Markdown itself can't resolve the reference, then autorefs kicks in, and fails. Indenting the last lines makes it part of the parameter description, so Python-Markdown sees it and can resolve the reference.

[pawamoy]

Some relevant context: mkdocstrings/python#217.

[Ravencentric]

That makes sense, thank you.

[Ravencentric]

Something else I noticed, using backticks also breaks it.

class SomeAPI:
    def __init__(self, base_url: str = "https://someurl.com", client: Client | None = None) -> None:
        """

        Parameters
        ----------
        base_url : str, optional
            The base URL of used for constructing API queries.
        client : Client, optional
            An [`httpx.Client`][] instance used to make requests. # Notice the backticks

            [`httpx.Client`]: https://www.python-httpx.org/advanced/#client
        
        """

WARNING -  mkdocs_autorefs: (package.MyClass.__init__) Could not find cross-reference target 'httpx.Client'

[pawamoy]

Indeed Python-Markdown doesn't support backticks in references I believe. That means it can't resolve the ref, then autorefs kicks in and fails too.