Skip to content

Examples in Google style do not show #46

@wxdrizzle

Description

@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".
image

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:
image

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:
image
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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions