Including markdown is buggy and local images do not work

[meghprkh]

Problem Description

If you include a markdown and try to link a local image it does not work

A clear and concise description of what the bug is.

Steps to reproduce the behavior:

1. Create doc/img.png
2. Create a doc/include.md with an image link ![img](./img.png)
3. .. include ../doc/include.md
4. The image is a broken link
5. 4. It works if the link was ./doc/img.png but that is incorrect markdown

System Information

Paste the output of "pdoc --version" here.
14.4.0

[mhils]

The logic for determining relative imports sits here:

pdoc/pdoc/docstrings.py

Lines 376 to 383 in 1b36ea2

	loc = source_file or Path(".")
	try:
	included = (loc.parent / val).read_text("utf8", "replace")
	except OSError as e:
	warnings.warn(f"Cannot include {val!r}: {e}")
	included = "\n"
	included = _rst_admonitions(included, loc.parent / val)
	return indent(included, ind)

The source_file argument should be the path of the current Python file where the docstring is in. We may need an additional call to embed_images here, see further up in the file. I don't have the capacity to dive deeper, but PRs are welcome! 😃

[meghprkh]

IMO regex based workarounds are a very bad idea. I might create a patch to address the issue at hand.

While switching to an extensible commonmark compliant markdown parser is a big change, it will remove need of such hacks. This link lists some of them. Markdown-it is fairly extensible.

[mhils]

This is a matter of setting the relative path correctly, not a matter of regexes or the markdown engine we are using. :)

[meghprkh]

I have created #692. Its a minimal fix but should work for the meanwhile :)