Display Text{String} from python docstring as plain string instead of markdown

[melonedo]

In #1239, I complained about python documentation not displayed in Pluto notebooks, which has been partially fixed in 0757a34 by parsing the returned docstring as markdown.

However, in my observation, python docstring is not standard markdown, at least not conformant to Julia's specification. For example, double backticks "``" are interpreted by Julia as LaTeX, but by Python (Sphinx) as inline code.

As a result, documentation for sympy.fourier_transform from SymPy.jl and plot from PyPlot.jl are not rendered perfectly:

[dralletje]

I'd say this is an issue in PyCall.
We don't really have a way to check if docs "come from python", and it would help other docs-based programs a lot if PyCall would convert this.
Could you open an issue with PyCall?

[stevengj]

If we're returning a Text string and not Markdown, why are you displaying it as text/markdown?

Shouldn't you be checking showable("text/markdown", docstring) to check whether a show("text/markdown") method exists?

[stevengj]

Even from Julia, documentation can be any show-able object, and you're supposed to be using the multimedia I/O machinery to decide how to display it.

[dralletje]

@stevengj its an exception so PyCall docs work

[stevengj]

I'm confused, why do you need an "exception" rather than just using display (or equivalent) for docstrings?

[dralletje]

Because PyCall (or python itself, don't know how deep this is embedded) doesn't think about exposing it as markdown (instead using Text), but as far as I could find python docs are generally implemented in markdown.

Ideally this would be fixed at a deeper layer, but AFAIK this fix works enough.

What problem are you addressing?

[stevengj]

but as far as I could find python docs are generally implemented in markdown.

You can't assume this. There are lots of Python packages with non-markdown docstrings

If an object doesn't have a text/markdown method for show, you should use the text/plain method. Treating it as text/markdown anyway is broken.

[dralletje]

Thanks for your feedback