feature: Option to link source

[reteps]

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

I would like to give users a way to view the source, but viewing it inline isn't that helpful; linking back to GitHub so they can see the version history is. Additionally, some extremely large functions benefit from this style, as an inline block takes up a lot of space.

Describe the solution you'd like

I have added a hook with this functionality upstream that overrides view_source for functions and classes, but I was unsure how to easily configure the base repo URL (which should happen outside of mkdocsstrings)

Here is the template override: https://github.com/PrairieLearn/PrairieLearn/blob/master/docs/mkdocstrings/python/material/function.html.jinja#L19

Context

You can see an example here: https://prairielearn.readthedocs.io/en/latest/python-reference/prairielearn/core/

Request

A link_source option that does what I want.

[pawamoy]

Thanks for the request @reteps! This was generally asked here https://github.com/mkdocstrings/mkdocstrings/issues/657 but I'll keep this issue as main one for Python.

[reteps]

@pawamoy Can you suggest a method to fetch the global mkdocs config from inside a template? If so, I can open a PR for this.

[pawamoy]

I'm trying to keep the templates agnostic to the SSG, so ideally we wouldn't pass the whole MkDocs config to them, only what is necessary, and in an explicit way (with a properly declared option). MkDocs users can make use of YAML features (anchors, aliases) if they wish to avoid repetition in mkdocs.yml.

Note however that your current approach only works for objects defined within the configured repository, not for objects declared in other packages. It would have to take the origin of an object into account to prevent rendering incorrect links to sources, and I'm not sure how to do that in a robust manner from mkdocstrings(-python) only.

Also, hardcoding main or master branches will render links that only work for a definite period of time, contrary to links using proper commit references, so you'll probably have to run some Git commands in subprocesses to get a commit hash. And I'm not sure I'd want that to happen in mkdocstrings-python.

The alternative, more robust solution is that Griffe handles that for us, providing the necessary Git remote+commit information (just like it already provides source info like file and line numbers), that the Python handler could then use in templates. It would be straight-forward for code within the current repository, but more involved for code within virtual environments, so we could start with the former only.

In any case, since there'll be a distinction between your own code and code from other packages, I think we'll need a new show_source_link option 🤔 WDYT? If you want to follow my suggestion and try and implement that in Griffe first, I can provide more guidance 🙂

[reteps]

If you want to follow my suggestion and try and implement that in Griffe first, I can provide more guidance 🙂

That sounds great, maybe we can discuss an implementation plan in the linked issue there.

[hmellor]

Just wanted to drop in to say that this would be something we'd be interested in for https://docs.vllm.ai/api/index.html

[pawamoy]

Implemented in Griffe, just needs the option and rendering on mkdocstrings-python now 🙂