Is it possible to pre-process docstrings?

[JuroOravec]

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:

	```django
	{% component "dynamic" is=table_comp data=table_data headers=table_headers %}
	    {% fill "pagination" %}
	        {% component "pagination" / %}
	    {% endfill %}
	{% endcomponent %}
	```

Which I'd like to pre-process into

=== "Syntax 1"

    ```django
    {% component "dynamic" is=table_comp data=table_data headers=table_headers %}
        {% fill "pagination" %}
            {% component "pagination" / %}
        {% endfill %}
    {% endcomponent %}
    ```

=== "Syntax 2"

    ```django
    {% dynamic is=table_comp data=table_data headers=table_headers %}
        {% fill "pagination" %}
            {% pagination / %}
        {% endfill %}
    {% enddynamic %}
    ```

The workarounds are, IMO, insufficient:

• Define the content tabs directly in the docstrings

  • ❌ This doesn't look nice in the tooltip in code editor

• Extract the examples, and then append them after the docstrings

  • ❌ If there will be a docstring with long text, then all the examples would have to appear at the end.

[pawamoy]

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 🙂

[JuroOravec]

@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 mkdocs.yml:

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            extensions:
            - scripts/docs_docstring.py:ComponentSyntaxes

But I wasn't able to run the extensions for the "local" config, e.g.

::: django_components.components.dynamic.DynamicComponent
    options:
      extensions:
      - scripts/docs_docstring.py:ComponentSyntaxes

[pawamoy]

That's one of the quirks of our architecture: upon the first ::: pkg.obj, Griffe loads the entire related package, with the extensions configured globally or locally. In subsequent ::: pkg.other_obj injections, the package is already loaded, so any extension configured locally does nothing. Have to properly document all this 😕

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 🙂).

[JuroOravec]

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.