Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

support for non-markdown docstrings is broken? #15424

Closed
stevengj opened this issue Mar 9, 2016 · 2 comments · Fixed by #15428
Closed

support for non-markdown docstrings is broken? #15424

stevengj opened this issue Mar 9, 2016 · 2 comments · Fixed by #15428
Labels
docsystem The documentation building system regression Regression in behavior compared to a previous version

Comments

@stevengj
Copy link
Member

stevengj commented Mar 9, 2016

One of the original key points of the docsystem design was that @doc could use any Julia object as a docstring, and writemime would be used to convert that object to different formats as needed. The default would be Markdown objects, but other objects would also be supported.

This seems to have been broken in a recent Julia 0.5 commit, causing JuliaPy/PyPlot.jl#198 because PyPlot uses "lazy" documentation objects that fetch docstrings from Python only when needed in order to speed up using PyPlot.

For example, @doc 15 f(x) = 2 used to work in Julia 0.4, associating 15 as the documentation object for f, but it now gives:

ERROR: MethodError: Cannot `convert` an object of type Int64 to an object of type Base.Markdown.MD
This may have arisen from a call to the constructor Base.Markdown.MD(...),
since type constructors fall back to convert methods.
Closest candidates are:
  convert{T}(::Type{T}, ::T)
  (::Type{BoundsError})(::ANY)
  (::Type{BoundsError})(::ANY, ::ANY)
  ...
 in convert(::Type{Nullable{Base.Markdown.MD}}, ::Nullable{Int64}) at ./nullable.jl:32
 in Base.Docs.DocStr(::Int64, ::Dict{Symbol,Any}) at ./docs/Docs.jl:134
 in eval(::Module, ::Any) at ./boot.jl:267
``
@stevengj stevengj added regression Regression in behavior compared to a previous version docsystem The documentation building system labels Mar 9, 2016
@MichaelHatherly
Copy link
Member

Sorry about that @stevengj, will fix asap.

@stevengj
Copy link
Member Author

stevengj commented Mar 9, 2016

Thanks for looking into it!

MichaelHatherly added a commit to MichaelHatherly/julia that referenced this issue Mar 9, 2016
Custom docstring support was lost in JuliaLang#15266. This remedies the
regressions introduced there as well as fixing `Text` and `HTML`
display signatures that were also broken, likely when `Function`
became an abstract type, and had gone unnoticed.

Also adds a test case based on PyPlot to hopefully avoid future regressions.

Fixes JuliaLang#15424.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docsystem The documentation building system regression Regression in behavior compared to a previous version
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants