Examples in Google style do not show

[wxdrizzle]

Edited. This issue has been solved by myself. Dear developer, just see my second comment below please, and confirm whether I am correct, or whether there is a better way. Then we can close this issue.

Describe the bug
I used the google style to write my python docstrings. The "examples" section is not rendered by mkdocstrings, while other sections such as "Parameters" and "Returns" work well.

To Reproduce
Just write a docstring like:

def foo():
    """
    Examples:
        We can print something:
        >>> print('foo')
        'foo'
    """

Expected behavior
I expect that the "examples" section is rendered, just like the previous python handler's behavior.

Screenshots
You can see nothing shown below "Examples".

System (please complete the following information):

• griffe version: 0.12.6
• Python version: 3.9.7
• OS: MacOS 12.2.1

Additional context
I tried to debug that. If I change the content in templates/python/material/_base/docstring/examples.html from

{{ log.debug() }}
<p><strong>{{ section.title or "Examples:" }}</strong></p>
{% for section_type, sub_section in section.value %}
  {% if section_type == "markdown" %}
    {{ sub_section|convert_markdown(heading_level, html_id) }}
  {% elif section_type == "examples" %}
    {{ sub_section|highlight(language="python", linenums=False) }}
  {% endif %}
{% endfor %}

to

{{ log.debug() }}
<p><strong>{{ section.title or "Examples:" }}</strong></p>
{% for section_type, sub_section in section.value %}
    {{ sub_section|highlight(language="python", linenums=False) }}
{% endfor %}

Then the section will be rendered but the markdown text is also rendered as code:

Therefore, I think there may be something wrong with {% if section_type == "markdown" %} or {% elif section_type == "examples" %}, making the value always "False". To confirm this, I add {{ section_type}} and {{ section_type == "examples"}} to the for loop, and then:

You can see that the section_type is DocstringSectionKind.examples, and {{ section_type == "examples"}} is False. I then tried {{ section_type == "DocstringSectionKind.examples"}}, but it is still False.

[wxdrizzle]

I solved this issue by changing {% if section_type == "markdown" %} to {% if section_type|string == "DocstringSectionKind.text" %}, and also changing {% if section_type == "examples" %} to {% if section_type|string == "DocstringSectionKind.examples" %}.

Now it looks like:

So for the developer: I think the corresponding code in the template of examples need to be modified in such way. Could you please confirm this?

How I got the solution:
After I found {{ section_type == "DocstringSectionKind.examples"}} is still False, I think although the type of section_type is indeed DocstringSectionKind.examples, but it is not equal to a string "DocstringSectionKind.examples". So I managed to change section_type to a string type. I tried str(section_type) but got an error when running mkdocs, from which I got to know that the language (?) is called "jinja2", so I searched "jinja2 how to convert variable to string", and found the answer is section_type|string. Finally I came up with the solution.

[pawamoy]

Hi again @wxdrizzle! Thanks for the detailed bug report, and the solution to the issue 😄
Indeed, I forgot to update this template: we now use enums and can't compare them directly to strings.
And markdown was changed to text.

So the final fix will look like this:

{% for section_type, sub_section in section.value %}
  {% if section_type.value == "text" %}
    {{ sub_section|convert_markdown(heading_level, html_id) }}
  {% elif section_type.value == "examples" %}
    {{ sub_section|highlight(language="python", linenums=False) }}
  {% endif %}
{% endfor %}

Do you want to send a PR (on the mkdocstrings/python repo) with that 🙂? If not, I'll do it in the afternoon anyway!

[pawamoy]

Done! Will release it soon.

[wxdrizzle]

Great work! Sorry that I just woke up due to the time difference. Thank you for the quick reply and quick fix @pawamoy 😄

[pawamoy]

Sorry that I just woke up due to the time difference

Haha no problem of course 😄