Is it possible to pre-process docstrings? #190
-
|
Hi, is it possible to pre-process docstrings? This if for django_components. There, we define classes that can be used as UI components in the Django template. The docstring includes an example usage within Django template. However, we support 2 (might be 3 in the future) different syntaxes. So while the component's docstring contains only the default syntax, I'd like in the documentation to use content tabs to be able to switch between the syntaxes. E.g. the docstring may contain an example like this: Which I'd like to pre-process into The workarounds are, IMO, insufficient:
|
Beta Was this translation helpful? Give feedback.
Replies: 1 comment 3 replies
-
|
Nice use-case @JuroOravec 🙂 The best way to pre-process docstrings is to write a Griffe extension. Quick example: import griffe
def _preprocess(docstring: griffe.Docstring) -> None:
docstring.value = re.sub(..., ..., docstring.value) # your preprocessing logic
# if you have a look at Griffe's API, you might be tempted to use docstring.parsed instead,
# but I don't recommend mutating the parsed version
# as there are chances it stops being cached in the future
class ComponentSyntaxes(griffe.Extension):
def on_class_instance(self, cls: griffe.Class, **kwargs) -> None:
if cls.docstring:
_preprocess(cls.docstring)Let me know if that helps! Happy to answer further questions 🙂 |
Beta Was this translation helpful? Give feedback.
-
|
@pawamoy Thanks a lot, really appreciate the fast reply! I'm still fairly new to mkdocs, but was able to get it working :) Just one hiccup - I got it working when I set the extension in the plugins:
- mkdocstrings:
handlers:
python:
options:
extensions:
- scripts/docs_docstring.py:ComponentSyntaxesBut I wasn't able to run the extensions for the "local" config, e.g. |
Beta Was this translation helpful? Give feedback.
-
|
That's one of the quirks of our architecture: upon the first If you wish to enable the extension for only a subset of objects, you can make it accept options, and pass paths to the objects you want in mkdocs.yml (the docs show how to do this 🙂). |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for the explanation! was able to make it work such that the extension is configured globally, and then inside it I check if the class as hand is one of those that should have the docstring transformed. |
Beta Was this translation helpful? Give feedback.
Nice use-case @JuroOravec 🙂
The best way to pre-process docstrings is to write a Griffe extension. Quick example:
Let me know if that helps! Happy t…