feature: Support footnotes in docstring parameters section

[dhirschfeld]

Is your feature request related to a problem? Please describe.

It would be good if I could use a footnote to link to a References section.

When I try the below:

        Parameters
        ----------
        timeout : float | httpx.Timeout, default 5.0
            Request a default timeout in seconds or provide a
            `httpx.Timeout` instance for finer-grained control[^1].

        References
        ----------
        [^1]: https://www.python-httpx.org/advanced/timeouts/

The back-link renders correctly in the References section but there is no link shown in the timeout section where the footnote [^1] appears to be ignored and rendered as plain text:

Describe the solution you'd like

The footnote should render as a superscript number and should be a link to the corresponding [^1]: in the References section.

[pawamoy]

Hi @dhirschfeld, thanks for the feature request!

I will probably close it in favor of #217. WDYT?

In the meantime the workaround is to move your references where relevant, for example [^1] in the timeout parameter description.

The general issue with a References section such as in your example above, is that references rendering depend on the tools in use. Yes, in MkDocs case, and more specifically Python-Markdown, references are always rendered at the bottom of the page/document (by default, I think it's configurable), but with other Markdown-to-HTML converter or SSGs they could be rendered under each relevant paragraph, or in a sidebar, etc. Front-end customizations might also move them elsewhere in the page.

Just a thing to take into consideration 😄 I'm nonetheless open to supporting this 🙂

[dhirschfeld]

I will probably close it in favor of #217. WDYT?

I'm happy to close this in favour of #217. I'm not fussed exactly how it's implemented, just that there's some way to add references to a docstring which get hyperlinked when rendered.