Embedded local images not working when inside __init__

[HackXIt]

Problem Description

With #460 the embedding of images was added.

However, the suggested usage of ![image](./path/to/image.png) does not work for me.

I am adding my README to the __doc__ of my __init__.py and it successfully adds the whole README. The markdown formatting works properly.

init.py

import os

README_path = os.path.join('README.md')
with open(README_path, 'r') as f:
    README = f.read()

__doc__ = README

Here is how an example image in the README is written: ![Mode Random](./docs/assets/Framework-Generic_random-mode.png)

But the generated doc still only contains the alt-text of the image, instead of the shown image.

Steps to reproduce the behavior:

1. Create a python module: src/__init__.py
2. Add a local image to __doc__: __doc__ = """![image](./path/to/image.png)"""
3. Generate pdoc: pdoc src

System Information

pdoc: 14.5.0
Python: 3.11.2
Platform: Linux-5.15.146.1-microsoft-standard-WSL2-x86_64-with-glibc2.36

[mhils]

We have file embedding working in CI, so this is surprising. Can you provide a repository with a minimal repro please?

[HackXIt]

Here you go: https://github.com/HackXIt/minimal-example-pdoc-embedded-image

Docs: https://hackxit.github.io/minimal-example-pdoc-embedded-image/src.html

Console log from browser

GET
https://hackxit.github.io/minimal-example-pdoc-embedded-image/assets/software-bug.png
[HTTP/2 404  21ms]

	
GET
	https://hackxit.github.io/minimal-example-pdoc-embedded-image/assets/software-bug.png
Status
404
VersionHTTP/2
Übertragen5,97 kB (9,38 kB Größe)
Referrer Policystrict-origin-when-cross-origin
Anfrage-PrioritätLow
DNS-AuflösungSystem

GET
https://hackxit.github.io/minimal-example-pdoc-embedded-image/assets/cat-on-keyboard.png
[HTTP/2 404  23ms]

	
GET
	https://hackxit.github.io/minimal-example-pdoc-embedded-image/assets/cat-on-keyboard.png
Status
404
VersionHTTP/2
Übertragen5,95 kB (9,38 kB Größe)
Referrer Policystrict-origin-when-cross-origin
Anfrage-PrioritätLow
DNS-AuflösungSystem

GET
https://hackxit.github.io/favicon.ico
[HTTP/2 404  0ms]

	
GET
	https://hackxit.github.io/favicon.ico
Status
404
VersionHTTP/2
Übertragen5,14 kB (9,12 kB Größe)
Referrer Policystrict-origin-when-cross-origin
DNS-AuflösungSystem

[HackXIt]

According to the browser log, the file could not be found (404), but my assumption would have been that pdoc handles this embedding appropriately, given that it is run from the root directory.

I tried moving the assets folder under docs as well, but it shows the same behavior.

[HackXIt]

Aah. I see the issue now.

After moving the assets folder under docs and referencing it via ./assets/... it finds the images on the main page. So it is a PATH issue after all, not an issue with pdoc.

So whenever referencing images, it must be relative to the output and if I include the . it will also include the path of the source directory.

It would however be nice, if pdoc would properly reference those embeddings to where they are located, or even move them entirely to the generation output.

[HackXIt]

So basically the issue is not a bug. It's simply related to the path of the image.

It is however a bit tricky for me, since I'm using the README of my project where I point the image to ./docs/<path-to-img>, whereas for pdoc it needs to point to ./<path-to-img>.

I think I can fix that my replacing the contents of the README as I load it into __doc__, but it would be a nice feature if pdoc would handle the path of the image during the embedding, so that the final output "just works".

[mhils]

Thanks for the reproducer. Your repro has a bunch of file inclusions, but I assume we are talking about the following snippet:

https://github.com/HackXIt/minimal-example-pdoc-embedded-image/blob/6670ac75258b6aecc233ec861a42d3dec389a5b0/src/init.py#L3-L7

The problem here is that pdoc just sees the contents of __doc__ and evaluates them in the context of the module source directory, i.e. minimal-example-pdoc-embedded-image/src. __doc__ contains ./assets/software-bug.jpg, and minimal-example-pdoc-embedded-image/src/./assets/software-bug.jpg does not exist, so embedding fails.

The best workaround here is to use an include directive: https://pdoc.dev/docs/pdoc.html#include-markdown-files. Here, pdoc is able to understand that we are changing the working directory and embedding images should work again.

[HackXIt]

Good to know that there is a markdown inclusion, I haven't seen that.

In regards to the inclusions in the docstring of functions in source files, is there a way to better handle the path in that case as well?

[mhils]

If you want to include external files, the best way is really https://pdoc.dev/docs/pdoc.html#include-markdown-files. Or you write your docstrings so that relative paths match for pdoc.