pdoc3 / pdoc3/pdoc

Local image not copied over to output directory

Open
#268 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
1.2k
Forks
146
PR merge metrics
No merged PRs in 30d

Description

Expected Behavior

When adding a local image (relative path) to the Python Docstring like this:

"""
# Test

.. image:: test.svg
"""

then the image should be shown in the generated documentation of this Python file.

Actual Behavior

No image is shown, although the HTML element is generated:

<img alt="" src="test.svg">

The network traffic (when hosted by pdoc3 --http) shows a 302 response with redirection to test.svg/ which then directly afterwards returns a 404 Not Found. The pdoc log states:

127.0.0.1 - - [12/Oct/2020 09:43:32] "GET /pdt/test.html HTTP/1.1" 200 -
127.0.0.1 - - [12/Oct/2020 09:43:32] "GET /pdt/test.svg HTTP/1.1" 302 -
127.0.0.1 - - [12/Oct/2020 09:43:32] "GET /pdt/test.svg/ HTTP/1.1" 404 -

Remote images (using URL) work but local images do not, which is a shame when the idea is to put all documentation within the repository/code. I also tested different image formats like png and jpg, but this did not make a difference.

Steps to Reproduce
  1. Create folder /tmp/pdoctest, within, create a subfolder pdt
  2. In the subfolder, copy an image file, create an empty __init__.py and a test.py file
  3. Paste the above docstring in the test.py file and save it. Make sure that the name of the image matches.
  4. Run PYTHONPATH="/tmp/pdoctest" pdoc3 --http : pdt
  5. In your browser, open http://localhost:8080/pdt/test.html
  6. The heading "Test" should be visible but not the image
Additional info
  • pdoc version: 0.8.1

If you require further information, please let me know!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue with the documented /tmp/pdoctest layout, pdt/test.py, and test.svg, then run pdoc3 --http : pdt. Start at the HTTP handling for /pdt/test.svg and trace why the request redirects to a trailing slash. Done means local images referenced by docstrings are served and displayed in the generated documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.