search

analytech-solutions / CBinding.jl

Automatic C interfacing for Julia
MIT License
132 stars 7 forks source link

Documenter bug on dynamic CBinding binding #89

Open fleimgruber opened 3 years ago

fleimgruber commented 3 years ago

While developing https://github.com/fleimgruber/DWDataReader.jl and working on the docs, I did

cd docs
julia make.jl

and got the error below. Documenter thinks this is a bug, but since the error is apparently on one of the dynamically generated bindings (DWDataReader.DWGetVersion in context.jl) I wanted to ask here about any ideas for this before reporting upstream. Are there other packages using CBinding with Documenter? I saw #16, so I guess there are no best practices yet concerning docs?

 Activating environment at `~/dev/DWDataReader.jl/docs/Project.toml`
┌ Warning: /home/fps/dev/DWDataReader.jl/src/file.jl:14: warning: the current #pragma pack alignment value is modified in the included file [-Wpragma-pack]
│   #include <DWDataReaderLib.h>
│            ^~~~~~ here
└ @ DWDataReader ~/dev/DWDataReader.jl/src/file.jl:14
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
┌ Error: Markdown2 conversion error for a docstring in DWDataReader.
│ This is a bug — please report this on the Documenter issue tracker
│   docstr.data =
│    Dict{Symbol,Any} with 5 entries:
│      :typesig    => Union{}
│      :module     => DWDataReader
│      :linenumber => 149
│      :binding    => DWDataReader.DWGetVersion
│      :path       => "/home/fps/.julia/packages/CBinding/kBUap/src/context.jl"
└ @ Documenter.DocTests ~/.julia/packages/Documenter/XIxke/src/DocTests.jl:80
ERROR: LoadError: MethodError: Cannot `convert` an object of type Documenter.Utilities.Markdown2.Link to an object of type Array{Documenter.Utilities.Markdown2.MarkdownInlineNode,1}
Closest candidates are:
  convert(::Type{T}, ::AbstractArray) where T<:Array at array.jl:554
  convert(::Type{T}, ::T) where T<:AbstractArray at abstractarray.jl:14
  convert(::Type{T}, ::LinearAlgebra.Factorization) where T<:AbstractArray at /buildworker/worker/package_linux64/build/usr/share/julia/stdlib/v1.5/LinearAlgebra/src/factorization.jl:55
  ...
Stacktrace:
 [1] Documenter.Utilities.Markdown2.Paragraph(::Documenter.Utilities.Markdown2.Link) at /home/fps/.julia/packages/Documenter/XIxke/src/Utilities/Markdown2.jl:120
 [2] _convert_block(::Markdown.Paragraph) at /home/fps/.julia/packages/Documenter/XIxke/src/Utilities/Markdown2.jl:227
 [3] iterate at ./generator.jl:47 [inlined]
 [4] collect_to!(::Array{Documenter.Utilities.Markdown2.CodeBlock,1}, ::Base.Generator{Array{Any,1},typeof(Documenter.Utilities.Markdown2._convert_block)}, ::Int64, ::Int64) at ./array.jl:732
 [5] collect_to_with_first!(::Array{Documenter.Utilities.Markdown2.CodeBlock,1}, ::Documenter.Utilities.Markdown2.CodeBlock, ::Base.Generator{Array{Any,1},typeof(Documenter.Utilities.Markdown2._convert_block)}, ::Int64) at ./array.jl:710
 [6] _collect(::Array{Any,1}, ::Base.Generator{Array{Any,1},typeof(Documenter.Utilities.Markdown2._convert_block)}, ::Base.EltypeUnknown, ::Base.HasShape{1}) at ./array.jl:704
 [7] collect_similar at ./array.jl:628 [inlined]
 [8] map at ./abstractarray.jl:2162 [inlined]
 [9] convert(::Type{Documenter.Utilities.Markdown2.MD}, ::Markdown.MD) at /home/fps/.julia/packages/Documenter/XIxke/src/Utilities/Markdown2.jl:214
 [10] doctest(::Base.Docs.DocStr, ::Module, ::Documenter.Documents.Document) at /home/fps/.julia/packages/Documenter/XIxke/src/DocTests.jl:78
 [11] doctest(::Documenter.Documents.DocumentBlueprint, ::Documenter.Documents.Document) at /home/fps/.julia/packages/Documenter/XIxke/src/DocTests.jl:57
 [12] runner(::Type{Documenter.Builder.Doctest}, ::Documenter.Documents.Document) at /home/fps/.julia/packages/Documenter/XIxke/src/Builder.jl:214
 [13] dispatch(::Type{Documenter.Builder.DocumentPipeline}, ::Documenter.Documents.Document) at /home/fps/.julia/packages/Documenter/XIxke/src/Utilities/Selectors.jl:170
 [14] #2 at /home/fps/.julia/packages/Documenter/XIxke/src/Documenter.jl:257 [inlined]
 [15] cd(::Documenter.var"#2#3"{Documenter.Documents.Document}, ::String) at ./file.jl:104
 [16] #makedocs#1 at /home/fps/.julia/packages/Documenter/XIxke/src/Documenter.jl:256 [inlined]
 [17] top-level scope at /home/fps/dev/DWDataReader.jl/docs/make.jl:3
 [18] include(::Function, ::Module, ::String) at ./Base.jl:380
 [19] include(::Module, ::String) at ./Base.jl:368
 [20] exec_options(::Base.JLOptions) at ./client.jl:296
 [21] _start() at ./client.jl:506
in expression starting at /home/fps/dev/DWDataReader.jl/docs/make.jl:3
fleimgruber commented 1 year ago

I just tried this again with Documenter.jl v1.1.0 and got a slightly different Traceback:

Sir? julia --project=. make.jl
┌ Warning: Unable to determine HTML(edit_link = ...) from remote HEAD branch, defaulting to "master".
│ Calling `git remote` failed with an exception. Set JULIA_DEBUG=Documenter to see the error.
│ Unless this is due to a configuration error, the relevant variable should be set explicitly.
└ @ Documenter C:\Users\LeimgruberF\.julia\packages\Documenter\9kOxY\src\utilities\utilities.jl:711
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
┌ Error: MarkdownAST conversion error for a docstring in DWDataReader.
│ This is a bug — please report this on the Documenter issue tracker
│   docstr.data =
│    Dict{Symbol, Any} with 5 entries:
│      :typesig    => Union{}
│      :module     => DWDataReader
│      :linenumber => 147
│      :binding    => DWDataReader.c"DW_CH_XML"
│      :path       => "C:\\Users\\LeimgruberF\\.julia\\packages\\CBinding\\PrYH5\\src\\context.jl"
└ @ Documenter C:\Users\LeimgruberF\.julia\packages\Documenter\9kOxY\src\doctests.jl:66
ERROR: LoadError: MethodError: no method matching iterate(::Markdown.Link)
Closest candidates are:
  iterate(::Union{LinRange, StepRangeLen}) at range.jl:872
  iterate(::Union{LinRange, StepRangeLen}, ::Integer) at range.jl:872
  iterate(::T) where T<:Union{Base.KeySet{<:Any, <:Dict}, Base.ValueIterator{<:Dict}} at dict.jl:712
  ...
Stacktrace:
  [1] _convert(nodefn::MarkdownAST.NodeFn{Nothing}, c::MarkdownAST.Paragraph, child_convert_fn::typeof(MarkdownAST._convert_inline), md_children::Markdown.Link)
    @ MarkdownAST C:\Users\LeimgruberF\.julia\packages\MarkdownAST\CZtZT\src\stdlib\fromstdlib.jl:33
  [2] _convert_block(nodefn::MarkdownAST.NodeFn{Nothing}, block::Markdown.Paragraph)
    @ MarkdownAST C:\Users\LeimgruberF\.julia\packages\MarkdownAST\CZtZT\src\stdlib\fromstdlib.jl:40
  [3] _convert(nodefn::MarkdownAST.NodeFn{Nothing}, c::MarkdownAST.Document, child_convert_fn::typeof(MarkdownAST._convert_block), md_children::Vector{Any})
    @ MarkdownAST C:\Users\LeimgruberF\.julia\packages\MarkdownAST\CZtZT\src\stdlib\fromstdlib.jl:34
  [4] convert (repeats 2 times)
    @ C:\Users\LeimgruberF\.julia\packages\MarkdownAST\CZtZT\src\stdlib\fromstdlib.jl:23 [inlined]
  [5] convert
    @ C:\Users\LeimgruberF\.julia\packages\MarkdownAST\CZtZT\src\stdlib\fromstdlib.jl:21 [inlined]
  [6] _doctest(docstr::Base.Docs.DocStr, mod::Module, doc::Documenter.Document)
    @ Documenter C:\Users\LeimgruberF\.julia\packages\Documenter\9kOxY\src\doctests.jl:64
  [7] _doctest(blueprint::Documenter.DocumentBlueprint, doc::Documenter.Document)
    @ Documenter C:\Users\LeimgruberF\.julia\packages\Documenter\9kOxY\src\doctests.jl:49
  [8] runner(#unused#::Type{Documenter.Builder.Doctest}, doc::Documenter.Document)
    @ Documenter C:\Users\LeimgruberF\.julia\packages\Documenter\9kOxY\src\builder_pipeline.jl:209
  [9] dispatch(#unused#::Type{Documenter.Builder.DocumentPipeline}, x::Documenter.Document)
    @ Documenter.Selectors C:\Users\LeimgruberF\.julia\packages\Documenter\9kOxY\src\utilities\Selectors.jl:170
 [10] #79
    @ C:\Users\LeimgruberF\.julia\packages\Documenter\9kOxY\src\makedocs.jl:248 [inlined]
 [11] withenv(::Documenter.var"#79#81"{Documenter.Document}, ::Pair{String, Nothing}, ::Vararg{Pair{String, Nothing}})
    @ Base .\env.jl:172
 [12] #78
    @ C:\Users\LeimgruberF\.julia\packages\Documenter\9kOxY\src\makedocs.jl:247 [inlined]
 [13] cd(f::Documenter.var"#78#80"{Documenter.Document}, dir::String)
    @ Base.Filesystem .\file.jl:101
 [14] #makedocs#77
    @ C:\Users\LeimgruberF\.julia\packages\Documenter\9kOxY\src\makedocs.jl:247 [inlined]
 [15] top-level scope
    @ C:\Users\LeimgruberF\dev\DWDataReader.jl\docs\make.jl:3
in expression starting at C:\Users\LeimgruberF\dev\DWDataReader.jl\docs\make.jl:3