[DISCREPANCY] Some Autodocumentation Not Translating Properly

[NovakZachary]

Describe the discrepancy Some parts of autodoc are not properly displayed in markdown. The only functionality I tested was code blocks and images, but it could be other things as well.

To Reproduce Steps to reproduce the behavior:

1. Write a function with docstrings in the reStructuredText style.
2. Include a code block in a specific language.
3. Include an image with directives (in my case, I only had :width: 500 px).
4. In any of the rst files, include .. autofunction:: [function name].
5. Build in markdown.
6. See output.

Expected output

• When looking at the converted markdown, the code block should be indented for it to show up at all. This is not the case.
• The image path remains the same as before so the relative path has changed. This could be remedied by either creating an image folder in the markdown built markdown directory (like how building in html works) or the path itself could be changed to reference the directory in docs/source.
• The image directives should be converted as well, but they do not show up at all.

Environment (please complete the following information):

• OS: Windows 11
• Version: 0.6.6

Additional context If there is something I am missing and this is not actually a discrepancy, I apologize. Thank you for this sphinx extension, it is incredibly useful.

[liran-funaro]

@NovakZachary Thanks for you report. Can you please attach a code example? That is, input file, output file, and expected output file. You don't have to put the entire code, just the relevant snippets. I'll be out for vacation next month, so I'll look at this once I get back.

[NovakZachary]

Hi Iiran,

Here is the docstrings from the relevant function:

    """
    Computes the one-sided Discrete Fourier Transform (DFT) of a one-dimensional
    real-valued time record.
    [2.1.1]

    :param time_record: (1D array) The input time series (array elements are real-valued)
    :param int samp_rate: The sampling rate (in samples per second)

    :return:
    * A one dimensional float array: DFT bin frequencies in Hz (real-valued)
    * A one dimensional float array: The DFT of the input time series (complex-valued)
    :rtype: float, float

    :example:
    .. code-block:: python

        ...code...

    .. image:: /images/dft_example.png
        :width: 500px

    """

The relevant rst file simply uses .. autofunction:: <function>.

When using make markdown, it issues this warning: WARNING: image file not readable: ic2sa/docs/source/images/dft_example.png

Curiously enough, it only warns about the image in one function, even though the same image directive is used. (Note: Neither relative nor absolute paths to image files remedies this issue)

Here is what the output looks like: (Note: Here I'm using the markdown preview extension in VS Code, but I've verified the same results using other markdown viewers.)

And here is what the output looks like when using make html:

Thank you for your help, and I hope your vacation goes well!

[NovakZachary]

@liran-funaro Upon further inspection, the problem seems to be in the difference between how make html and make markdown handle image references in docstrings. In the former, another folder with the images is created: /docs/build/html/_images/, which overwrites the path of all autodoc image references in built html files. This is not the case for sphinx-markdown-builder, where the path is not changed nor is a new directory with the referenced images created during build.

The workaround is to anticipate this and use a relative path that would lead to the images folder from where the built markdown files are rather than the source. However, this then breaks make html as when looking at the image references, it will not be able to find the image directory. For instance, it would see ../../source/images/ and determine it does not actually exist as a relative path from the source directory itself.

It would be nice to have it automatically change the path to reference the source images or, similar to make html, create another folder of the same images and overwrite the autodoc image paths when converting to markdown.

Sorry I wasn't able to realize something so simple sooner!