Support for python code execution inside a documentation

[petrhrobar]

Is there currently a feature that allows to source some python function and output the function's output?

Suppose I have a function:

def func(name: str, age: int):
      """
       This function prints your name and age.

        ```python
        >>>func("Thomas", 15)
        >>>hey Thomas who is 15.
        ```
        
         """
        return f"hey {name} who is {age}."

Now docstring provides an example and it would be rendered. However, the function example is kind of "hardcoded" when I change the function and not the docstring, the example output does not change as it is static.

Would it be possible to also some e.g.:

.. execute_code::

from src.example import func
func("Petr", 101)

This would always change the output as the function is being executed.
I have been looking at sphinx feature HERE

[pawamoy]

Take a look at Markdown Exec (I'm the author). It should be possible to use the extension in docstrings code blocks as well, given you are using mkdocstrings to inject them in your pages, though I did not test that.

Example:

def func(name: str, age: int):
    """
    This function prints your name and age.

    ```python exec="yes" source="tabbed-left"
    from module import func  # you still have to import it :/
    print(func("Thomas", 15))
    ```
    """
    return f"hey {name} who is {age}."

The source="tabbed-left" option requires that you also use the pymdownx.tabbed extension.

UPDATE: updated the example.

[facelessuser]

An example of it dynamically rendering the README.md file from a raw link: https://facelessuser.github.io/coloraide/playground/?notebook=https%3A%2F%2Fraw.githubusercontent.com%2Ffacelessuser%2Fcoloraide%2Fmaster%2FREADME.md

[facelessuser]

Finally got a custom fence up. https://gist.github.com/facelessuser/53fa4d93f27c252fda813b5e0ba7325c

@pawamoy I know you maintain https://github.com/pawamoy/markdown-exec. I saw you have some form of Pycon support, but I think it is very different. You may find this comment useful as it has examples: facelessuser/pymdown-extensions#1690 (comment).

I hesitate to add something directly like this to Pymdown Extensions, but it may make sense in something like markdown-exec? Either way, figured I'd post this as some may find it useful. I'll probably be trialing it in some other projects.

[pawamoy]

In Markdown Exec, the output of pycon code blocks is concatenated at the end. Your solution is better in that the output is inserted where it should be, and not concatenated at the end 👍 So I could definitely reuse some of your code to improve the UX. But I'm not sure how I'd use the custom fence itself. As you mentioned it, our goals are very different, so the custom fence might not be a good fit in Markdown Exec.

[facelessuser]

That's fair. My approach is more aimed at dropping in normal python code, but then executing it and displaying it as an example in pycon. As it was relevant to the discussion, and I had mentioned I would probably do this, I figured I make a callback here. Regardless, I have use for it in some other projects, I'll figure out what to do with it moving forward.

[pawamoy]

Yes of course, thanks for updating this discussion and mentioning me 🙂