Include external file contents from inside docstring?

[mdaeron]

Is there a way to inject the contents of an external file from inside a docstring?

Using pdoc I can do the following:

def foo():
    """
    Example usage:
    ```py
    .. include:: ../code_examples/foo.py
    ```
    
    Resulting output:
    ```
    .. include:: ../code_examples/output.txt
    ```
    """
    return "foo"

Is something like like possible using mkdocstrings? I tried something using mkdocs-include-markdown-plugin but couldn't get it to work.

[pawamoy]

Can you show what you tried with mkdocs-include-markdown-plugin and why it didn't work?

You could also try snippets.

[mdaeron]

Here's what I tried:

.
├── docs
│   ├── 1-tutorial.md
│   ├── 2-how-to.md
│   ├── 3-reference.md
│   ├── 4-explanation.md
│   ├── foo.txt
│   └── index.md
├── foo.txt
├── mkdocs.yml
└── src
    └── cromulous
        ├── __init__.py
        └── foo.txt

mkdocs.yml:

site_name: Cromulous Documentation

theme:
    name: material

plugins:
    - search
    - mkdocstrings:
        default_handler: python
        handlers:
            python:
                options:
                    show_root_heading: true
                paths: [src]
    - include-markdown:
        encoding: ascii

src/cromulous/__init__.py:

"""
Docstring for `cromulous`
"""

def add(a, b):
	"""
	Docstring for `add()` function

	{% include-markdown "foo.txt" %}

	Examples:
		>>> add(4.0, 2.0)
		6.0
		>>> add(4, 2)
		6.0

	Args:
		a (float): A number representing the first addend in the addition.
		b (float): A number representing the second addend in the addition.

	Returns:
		s (float): A `number` [representing](https://daeron.fr) the arithmetic sum of `a` and `b`.
	"""
	return float(a + b)                                                                                                                                                                                            

This yields:

[pawamoy]

Oh, yeah, that's because docstrings do not pass through other MkDocs plugins, only Markdown extensions. Snippets will work better :)

[mdaeron]

I'll look into snippets as well, thanks.