Embedded file in a docstring

[gadsc]

Hello! Hope you are doing good :)
Do you know if it's possible to reference a code snippet inside the docstring? Something like this. I've tried many approaches without any success :(

Btw awesome library 🎉

Thanks in advance.

[pawamoy]

That's a good idea for a new Markdown extension I guess 🙂

[gadsc]

Hello, thanks for the quick answer!
Do you mean a mkdocstring extension, handler extension or other kind of extension?
I was able to render the code inside a markdown file creating a pluglet for mkdoc directly, but when I try to use it in the docstring it's just escaping my function 😭

Another question not related to it, do you know if it's possible to render the full enum path value? Right now when I have a enum it's just printing value, example:

FORMATS = [ value, value, value]

The real code is something like:

class Format(Enum):
    JDBC = "jdbc",
    [...]

FORMATS = [ Format.JDBC.value, [...]]

[pawamoy]

I mean a Python-Markdown extension. Basically an inline processor that matches against GitHub links, fetches the specified code lines through GitHub's API, and displays them like on GitHub. Or a different kind of processor which handles different markup than simple GitHub links.

An alternative would be a custom pymdownx superfence. It's easier to develop, but would be more verbose for users:

```github-snippet
your github link
```

I was able to render the code inside a markdown file creating a pluglet for mkdoc directly, but when I try to use it in the docstring it's just escaping my function 😭

Other pluglets (I suppose through mkdocs-macros?) or plugins can only see the docstrings once they're converted to HTML. They cannot see the original docstrings written in Markdown (unless hacks with mkdocs-macros). If you share your code, and the inputs/outputs you get, I can try to provide more guidance.

---

Regarding enum values, can you open a new issue? I've experienced the same thing 👍

[gadsc]

I tried through mkdocs-macros, based on this comment, only changing that right now we should use env.macro as decorator instead macro.
This is how I tried to use it:

class ExecEnv(object):
    """Represents the basic resources regarding the engine execution environment.

    Currently, it is solely used to encapsulate the logic to get a Spark session.
    ```
        {{ external_markdown("docs/test.md") }}
    ```

    Attributes:
        SESSION: Spark Session

    Examples:
        {{ external_markdown("docs/test.md") }}
    """
    [...]

This was the output:

Going to test the py-markdown and the superfence and post an answer here, thanks a lot for the answer :)

I've created the enum issue

[pawamoy]

Take a look at this: mkdocstrings/mkdocstrings#615 (comment).
It should help you getting macros to work in docstrings 🙂

[gadsc]

It worked perfectly :)
Thanks for this magic trick :D