search

JuliaPy / PyCall.jl

Package to call Python functions from the Julia language
MIT License
1.46k stars 187 forks source link

A better type for docstring #949

Closed melonedo closed 2 years ago

melonedo commented 2 years ago

https://github.com/JuliaPy/PyCall.jl/blob/e3e3008ee1b3e449c6382293f58a1f85384beea6/src/PyCall.jl#L260-L268 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 commented 2 years ago

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 commented 2 years ago

https://github.com/JuliaLang/julia/commit/86639e1abae97a7f46e8daa9ec83466865c854f4 It is deprecated since 1.7.

stevengj commented 2 years ago
  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 commented 2 years ago

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

stevengj commented 2 years ago

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 commented 2 years ago

See also JuliaLang/julia#43532.