Preprocessing docstrings (for link regex-replace)

[ssweber]

I wasn’t quite sure if this should be implemented in mkdocstrings, autorefs, or griffe.

I have a project that uses a simple convention for referencing other classes/functions/attributes:

Example:

See `ClassName.FunctionName` documentation for more details

Is there a way for me to hook a function to replace:

`ClassName.fn` with [fn][long_prefix.ClassName.fn]

or

`ClassName` with [ClassName][long_prefix.ClassName]

Before mkdocs/autorefs converts it into a link?

For now I’ll run a pre-processing script on the throw-away branch before running mkdocs serve/gh-deploy.

I think this allows a simpler and flexible solution to others desire for automatic links (See Also section), and/or relative link handling… without having to adding a bunch of markdown to the source-code.

[pawamoy]

You could pre-process docstrings with a Griffe extension. See the docs: https://mkdocstrings.github.io/griffe/extensions/.
Running a regex-replace on the docstring could do the trick, though it would be your responsibility to find out the complete path of the object. That seems doable given you'll know the parents of the object being pre-processed.

[ssweber]

Perhaps that’s simply unsupported at the moment?

Support for documented attributes: attributes (variables) followed by a docstring (triple-quoted string) will be recognized by Griffe in modules, classes and even in init methods.

If it’s not too difficult, could you point me in the right direction where I could work on adding post_init to this list?

[ssweber]

Looks like perhaps in https://github.com/mkdocstrings/griffe/blob/1e7b869b7345b30185e6bf634bc4f848c940172f/src/griffe/agents/visitor.py

[ssweber]

Sorry for the noise, starting to wrap my head around how the extensions work in griffe (really nice btw!).

Looks like I can for the time-being hook into on_attribute_node, copying over how it grabs the attribute docstring for __init__ and make it work for __post_init__. May need to strip the “self.” from the name? I’ll add another gist once I’ve figured it out and (if you like the idea), create a pull request to add to main.

[pawamoy]

No worries, I work this way too: creating issues/discussions and answering myself haha. Will try to answer later.

[ssweber]

That’s funny :) I think it’s helpful for the next person who has a similar issue. Thanks for being welcoming.

[ssweber]

I opened a small issue/pr in the griffe branch to handle __post_init__. I didn't know how to easily write an extension to do it externally.

[pawamoy]

Yep, to support this in extension we would probably need to expose the visitor/inspector to extensions.
I answered in the issue you opened 🙂