mkdocstrings
mkdocstrings copied to clipboard
mkdocstrings
Add ability to link to source code on GitHub
Similar to the sphinx.ext.linkcode extension:
- https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html
This is already implemented on master in https://github.com/mkdocstrings/mkdocstrings/pull/287 Thanks for signaling the need for it
Great! It didn't click for me that #287 would allow for this. Cheers, and sorry for the noise!
Wait, sorry-- I think I misunderstood your request. I pointed to an ability to link to a documentation website, which would only hopefully have a link to the source code. But actually mkdocstrings-Python has no ability to link to the source code, only to embed it. It would be possible to implement similarly to what I did in mkdocstrings-Crystal: Usage example: https://github.com/athena-framework/website/blob/befd26027e7e0465a13a5a0e1377fc18ae3092a6/mkdocs.yml#L55 Code: https://github.com/mkdocstrings/crystal/blob/b724d9d16b9a762821e58449ed0248fb7bee1042/mkdocstrings/handlers/crystal/collector.py#L106 But the links would probably need to know about Git commit hashes and such, but mkdocstrings so far has not entered the territory of understanding SCM systems
It would be possible to implement similarly to what I did in mkdocstrings-Crystal
I think that looks like what I'm after - hyperlinks to actual files on GitHub. For me, it's got a lot more value than just the source as every line has the associated commit message and PR reference (blame) which IMHO is a fundamental part of the documentation of source code.
But the links would probably need to know about Git commit hashes and such
You'd hopefully be able to get that using either __version__, pkg_resources or importlib.metadata
Well summarized by @oprypin:
the links would probably need to know about Git commit hashes and such, but mkdocstrings so far has not entered the territory of understanding SCM systems
Not sure we want to enter such a territory. However I believe this could be achieved with a combo of extra plugins and template overriding. mkdocstrings-sourcelink might interest you.
