Support reference-style Markdown links in Docstring rendering

[MaddyGuthridge]

I am using mkdocstrings to build documentation for my project, but have noticed that when I use Markdown's reference-style links in order to link various functions and classes in my code together. For example, [foo.bar][] should render as a link to the bar object in the foo module.

This works great for my documentation site, but means that users of my package who use VS Code's intellisense have a suboptimal experience as the Python extension renders this markdown incorrectly.

A minimum acceptable fix would be to only render the contents in the left-hand square brackets and ignore the link, which at least wouldn't lead to incorrect formatting.

Optimally, it'd be nice to have clicking on these links take users to the linked function definition, and show that function's documentation on hover, however I understand that this may be more challenging to implement depending on the capabilities of VS Code.

[debonte]

Notes from triage:

• Confirmed that this style of link is part of the Markdown standard -- https://daringfireball.net/projects/markdown/syntax#link
• Assuming that we are providing this markdown content to VS Code's renderer without messing it up somehow (ex. escaping), this issue should be transferred to vscode and it would be up to them to fix.

[StellaHuang95]

This looks like an enhancement in pylance to me. For the [foo.bar][] example above, when pylance does convertDocStringToMarkdown, it can:

1. Take the original docstring, the name of the module, and the name of the object as input.
2. Obtain the file path of the module and the line number of the object within the module.
3. Create a properly formatted Markdown link using the file path and line number and replaces the placeholder ([foo.bar][]) in the docstring with the generated link.

Above would provide the capability to navigate to the foo.bar object when the user clicks on it in VSCode.

[pawamoy]

Note that, specifically, mkdocstrings supports arbitrarily-deep nested dotted-path in these Markdown references. That's a lot of concatenated words, so let me give some examples of what is supported in mkdocstrings:

• [pkg][]
• [pkg.mod][]
• [pkg.mod.func][]
• [pkg.mod.Class][]
• [pkg.mod.Class.method][]
• [pkg.mod.Class.NestedClass][]
• [pkg.mod.Class.NestedClass.attr][]
• etc.

Supported reference formats:

• [title][identifier]
• [identifier][]
• [`identifier`][]

[identifier] (without [] suffix) is not supported.

[debonte]

Create a properly formatted Markdown link using the file path and line number and replaces the placeholder ([foo.bar][]) in the docstring with the generated link.

We can associate a command (go to def) with the string.

[debonte]

Moving this issue to discussion as an enhancement request for comments and upvotes.