A better type for docstring

[melonedo]

PyCall.jl/src/PyCall.jl

Lines 260 to 268 in e3e3008

	function Base.Docs.doc(o::PyObject)
	if hasproperty(o, "__doc__")
	d = o."__doc__"
	if !(d ≛ pynothing[])
	return Base.Docs.Text(convert(AbstractString, d))
	end
	end
	return Base.Docs.Text("Python object (no docstring found)")
	end

Docstring for python objects have the type Base.Docs.Text{String}, which has been deprecated. Since python documentation is usually in RST format, maybe we could create a type for that?

This has caused trouble in Pluto when displaying documentation in the help panel.

[stevengj]

Since when is it deprecated?

If it's a Text type, it seems like a bug in Pluto to display it as markdown, since

julia> showable("text/markdown", Docs.Text("foo"))
false

It should be showing it as text/plain.

[melonedo]

JuliaLang/julia@86639e1
It is deprecated since 1.7.

[stevengj]

1. It might in theory be removed in Julia 2.x, but it will be maintained for all Julia 1.x releases. (It might also be simply non-exported in 2.x, in which case Docs.Text will continue to work.)
2. We would just replace it with something exactly equivalent (a type that has a show method for text/plain but not for text/markdown), so why bother?
3. Regardless of what type we use, we will trigger the same Pluto bug if they are incorrectly assuming all docs are markdown.

[melonedo]

I think you are right, another type won't fix the issue about Pluto. Nevertheless it is better to avoid deprecated interfaces.

[stevengj]

Closing this as it's not an issue in Julia 1.x, and the only alternative would to be to re-implement Docs.Text.

[stevengj]

See also JuliaLang/julia#43532.