Find parent doc string for relative crossrefs

[analog-cbarber]

mkdocstrings does not currently support references to members not explicitly defined in subclass, so
instead of just being able to write something like [foo][.] you might have to write [foo][(m).ParentClass.]
or worse.

It would be nice if we could automatically handle this redirection.

[analog-cbarber]

I think that the mkdocstrings render method already handles the case where the target class does not directly define the method. What is not handled is when the target class overrides the method but does not provide a doc string. In that case, we would like to redirect to the closest ancestor that provides a doc-string.

Probably mkdocstrings should do that, so it may not be worthwhile trying to fix that in this extension.

[pawamoy]

I recently released a Griffe extension to inherit docstrings, as part of the Insiders program.

[analog-cbarber]

The griffe-inherited-docstrings extension is now in mkdocstrings-python 1.8. Maybe this will make this issue moot?

[pawamoy]

The griffe-inherited-docstrings extension is now in mkdocstrings-python 1.8.

Correction: it's now free, and was released at the same time as mkdocstrings-python 1.8 🙂

Maybe this will make this issue moot?

I suppose so. It's not always easy to remember exactly what mkdocstrings-python and autorefs do, but I think they do this:

• pkg.mod.Class.meth not found
• ask Python handler aliases for this identifier
• try each one to see if we have an URL for it
• link to the first that has an URL

The last fix in mkdocstrings-python regarding this behavior is from august: https://mkdocstrings.github.io/griffe/changelog/#0351-2023-08-26, so I'm surprised it didn't work for you. But I might forget something. As I said, not easy to remember the exact flow 😄

[analog-cbarber]

Ah right. I didn't read that closely enough. So you need to install the https://mkdocstrings.github.io/griffe-inherited-docstrings/?

Is there a reason that was not just bundled directly into griffe or mkdocstrings-python?

[pawamoy]

Yep, you can read the relevant discussion here: mkdocstrings/griffe#96. In short: it would have been hacky in both mkdocstrings-python and Griffe. With current Griffe's architecture, inheriting docstrings is a permanent side-effect. Back and forth inheriting/un-inheriting docstring would not have been super elegant or efficient. So it was best implemented as an extension.

[analog-cbarber]

I guess I should just update the documentation to mention this exetension.