Support for examples section

[jaimergp]

Hi! I would like to start by saying this project has made mkdocs usable for our team and we are SO excited about finally ditching RST! I cannot emphasize this enough: Thank. You.

The only thing we are missing is that, currently, mkdocstrings doesn't support an Examples section, which normally include doctest formatted blocks. For example:

def example_function(arg1, kwarg=None) -> object:
    """
    Example function to demonstrate how APIs are rendered

    Parameters:
        arg1 (dict): Some description for this argument.
            This type (in parenthesis) is ignored.
        kwarg: Some more descriptions

    Returns:
        A description for the returned value

    Examples:

        >>> 2 + 2 == 4
        False

    """
    pass

gets rendered as:

The style is not bad, but it could be even better! Notice how pytest is able to parse the block just fine.

I can get what I want by using this other docstring:

def example_function(arg1, kwarg=None) -> object:
    """
    Example function to demonstrate how APIs are rendered

    Parameters:
        arg1 (dict): Some description for this argument.
            This type (in parenthesis) is ignored.
        kwarg: Some more descriptions

    Returns:
        A description for the returned value

    __Examples__

    ```python
    >>> 2 + 2 == 4
    False

    ```
    """
    pass

, but I find it a bit annoying (in order of importance):

1. Manually hardcoding the Examples heading style
2. Having to specify the code fences
3. Needing an extra blank line before the closing triple backticks so pytest can get the doctests correctly.

Maybe a good compromise would be to just add Examples to the recognized headers? That way I could write:

def example_function(arg1, kwarg=None) -> object:
    """
    Example function to demonstrate how APIs are rendered

    Parameters:
        arg1 (dict): Some description for this argument.
            This type (in parenthesis) is ignored.
        kwarg: Some more descriptions

    Returns:
        A description for the returned value

    Examples:

        ```python
        >>> 2 + 2 == 4
        False

        ```
    """
    pass

, which currently does not work as intended:

I'd be happy to help and contribute a PR if needed, but if I understood correctly, you are currently refactoring the backend and I don't know if this is the best moment to add a feature.

Thanks a lot!

[pawamoy]

Hi @jaimergp, thank you very much for the kind words and the very detailed issue! I'm glad that your team is enjoying this project 🙂

I totally agree that examples must be supported, and I think the preferred way would be the first you wrote, but it's open to discussion of course.

This feature request is one more thing in favor of implementing a proper "google-style docstring markdown extension". We currently parse docstrings in mkdocstrings (and soon in another project responsible for loading the docs only), but it would definitely be way better to have an extension doing that. It would have its own challenges but I think I came with a good design. This design is unfortunately still only available in my mind, but I plan on writing it down here, in a pinned issue, with a "needs help" tag. This would be great if contributors could help with it!

So, as you said in the last paragraph, now is not a good time for such a feature, but I hope I'll be able to come soon with the desired architecture, which will allow us to iteratively improve mkdocstrings.

You'll hear from me when things have moved forward 🙂

[pawamoy]

Hey, I'm close to a new release of mkdocstrings with the new architecture. The code responsible for parsing docstrings is now hosted at https://github.com/pawamoy/py-tkdocs, so I'm transfering this issue over there!

[jaimergp]

Oh, great news! Yes, of course, no probs!

Do you need help testing stuff out?

[pawamoy]

Well sure, I'll publish a new version of mkdocstrings, v0.9.0, and if you can test it to see if there are any bugs and report them it would be great 🙂

Then we'll be able to improve the handling of Examples section 😄

[pawamoy]

Hey again @jaimergp

Do you still want to contribute a PR to support the examples sections? I can guide you through the code if needed.

[jaimergp]

Sure! Where should I start looking in?

[pawamoy]

All the changes should happen in src/pytkdocs/parsers/docstrings.py.

• add a TITLES_EXAMPLES constant at the top, like TITLES_RETURN
• add a type to the Section.Type "enum"
• add a read_examples_section method to the DocstringParser class. It should be similar to read_return_section
• handle such sections in the parse method. Again, should be similar to how the return sections are handled

Now this would be the pytkdocs part. Then in mkdocstrings we would need to update the docstring.html template to support these type of sections 🙂

[pawamoy]

Any progress @jaimergp? If not, and if you don't mind, I'll start working on this 🙂

[jaimergp]

Sorry @pawamoy, I've been very slow to start new side projects and haven't been able to contribute time to this. Please go ahead and take over! Let me know if I can help you test the usage once it's ready!

[igonro]

Hey @pawamoy, how is this feature going? I would be interested too. I think I could help if needed.