mkdocstrings
feature: Allow for syntax that results in the same output as using `~` in rST on classes and methods
Is your feature request related to a problem? Please describe.
I am working on shifting our documentation from Sphinx to MkDocs. My project lead sees nearly everything as either equivalent or better, except for linking syntax. He is used to ":class:`~module.ClassName`" being rendered as ClassName, ":meth:`~module.Class.method`" being rendered as method. It would be nice to maintain something similar to this feature when moving to MkDocs.
Describe the solution you'd like
What we'd like to see is something like the following (using an actual example):
[`~toga.widgets.canvas.Context`][]
Render as Context and link to the class documentation for Context.
As well:
[`~toga.widgets.canvas.Context.fill`][]
Would render as Context.fill, and link to the documentation for the fill method.
It could be something like:
[][`~toga.widgets.canvas.Context.fill`]
In the event that there's no way to change what is rendered in one of these links.
Describe alternatives you've considered
I am using the current linking syntax with custom text to render the class documentation links as the class or method name only.
Additional context
I looked at the code for autorefs, but it's outside my understanding to have any idea whether this is possible or how to go about doing it. To that end, I have no frame of reference for the complexity of this request.
Hi @kattni, thanks for all the valuable feedback, reports and feature requests! 🚀
The plan with autorefs is to support advanced syntax for cross-references at some point, yes, though I'm not sure I want to reuse Sphinx's (or is it rST? I never know).
[`~toga.widgets.canvas.Context`][] makes sense, but the issue is that autorefs is language agnostic, and ~ could have a meaning in other languages than Python, so we must tread carefully here.
What I was envisioning for an advanced syntax is more something like this: [`path.to.symbol`][]{ option="value" }. It's not as pretty, it's more verbose, but at least it doesn't mess with the id part of the link. That said, it could be difficult to get access to such attributes after the link (I think Python-Markdown will not let us do that easily, for technical reasons).
So, for now, I'm not sure how I'd want to tackle this 😕
Hi - thanks for the fast response; I'm the aforementioned project lead :-)
The plan with autorefs is to support advanced syntax for cross-references at some point, yes, though I'm not sure I want to reuse Sphinx's (or is it rST? I never know).
FTR: the linking syntax is all part of the Sphinx extensions to rST.
What I was envisioning for an advanced syntax is more something like this:
[`path.to.symbol`][]{ option="value" }. It's not as pretty, it's more verbose, but at least it doesn't mess with the id part of the link. That said, it could be difficult to get access to such attributes after the link (I think Python-Markdown will not let us do that easily, for technical reasons).
Throwing another idea out there: [`path.to.symbol`]{value}. I don't know how well that fits into the existing parser, but given there's already support for []() and [][], adding another pattern in the same vein seems at least plausible; and by way of a mnemonic, {} is clearly a reference to code 😄.
FTR: the linking syntax is all part of the Sphinx extensions to rST.
Thanks!
Throwing another idea out there:
We still need to support specifying the id and custom title, as well as passing options: [Some title][some.id]{ some="option" }. In any case, we will have to hook in Python-Markdown a bit more than what we currently do (i.e. more than just reusing the reference link inline pattern).
https://github.com/mkdocstrings/autorefs/issues/67 is also a bit relevant 🙂