Docile gives me the weirdest bugs

[zenna]

I have been trying to use Docile, but it gives me the weirdest bugs.

Sometimes when a @doc is included in a certain place my module won't load. It get's caught in some infinite loop.

In other places, for example the following snippet taken from here

for finame in ["symbolic.jl",
               "executable.jl",
               "randarray.jl"]
  @show "including $finame"
  include(joinpath("randvar", finame))
end
@show "got here"

Docile causes Julia to just skip over including executable.jl or randarray.jl.

"includign $(finame)" => "including symbolic.jl"
"Got here" => "Got here"

Unfortunately, I haven't been able to reproduce these thigns in a simple example, but the problems go away when I remove all @doc or use Julia0.4 with its own support for @doc

[MichaelHatherly]

Thanks for reporting this @zenna. Which version of Docile are you using, also what's the extact commit from Julia 0.3 you're on?

[MichaelHatherly]

BTW, have you tried using the new bare docstrings that were recently added to Base? Docile also supports bare docstrings in Julia 0.3 without needing to be imported into your package, it'll automatically search loaded packages when ? mode is called.

[MichaelHatherly]

Having a bit of trouble getting Sigma.jl to load. Which other deps do I need? Any particular branches that I should be checking out rather than master?

Got it working, well breaking with the following backtrace rather:

julia> import Sigma
"including $(finame)" => "including symbolic.jl"
"Got here" => "Got here"
ERROR: all_functional_randvars not defined
 in anonymous at no file
 in include at ./boot.jl:245
 in include_from_node1 at ./loading.jl:128
 in include at ./boot.jl:245
 in include_from_node1 at ./loading.jl:128
 in include at ./boot.jl:245
 in include_from_node1 at ./loading.jl:128
 in reload_path at loading.jl:152
 in _require at loading.jl:67
 in require at loading.jl:51
while loading /home/mike/.julia/v0.3/Sigma/src/solver/dreal.jl, in expression starting on line 36
while loading /home/mike/.julia/v0.3/Sigma/src/solver.jl, in expression starting on line 12
while loading /home/mike/.julia/v0.3/Sigma/src/Sigma.jl, in expression starting on line 155

[zenna]

@MichaelHatherly I"m working on getting Sigma easier to load.

I've been using julia version 0.3.10. And Docile 0.5.12.

I just read about the bare strings earlier today, I'm going to change to that, see if it helps.

[MichaelHatherly]

With this diff (edit: apologies for the whitespace mangling my editor has done to the diff) I've managed to get import Sigma to work – with a couple of ambigouity warnings:

julia> import Sigma
Warning: New definition 
    +(T<:Real,RandArray{T<:Real,N}) at /home/mike/.julia/v0.3/Sigma/src/randvar/randarray.jl:150
is ambiguous with: 
    +(Bool,AbstractArray{Bool,N}) at array.jl:771.
To fix, define 
    +(Bool,RandArray{Bool,N})
before the new definition.
Warning: New definition 
    +(RandArray{T<:Real,N},T<:Real) at /home/mike/.julia/v0.3/Sigma/src/randvar/randarray.jl:154
is ambiguous with: 
    +(AbstractArray{Bool,N},Bool) at array.jl:770.
To fix, define 
    +(RandArray{Bool,N},Bool)
before the new definition.
Warning: New definition 
    -(T<:Real,RandArray{T<:Real,N}) at /home/mike/.julia/v0.3/Sigma/src/randvar/randarray.jl:150
is ambiguous with: 
    -(Bool,AbstractArray{Bool,N}) at array.jl:773.
To fix, define 
    -(Bool,RandArray{Bool,N})
before the new definition.

julia> 

You'll see I've removed the for-looped include calls, which seem to be part of the problem. Not sure what's causing Docile to interact oddly with them.

[MichaelHatherly]

I just read about the bare strings earlier today, I'm going to change to that, see if it helps.

Since you don't need to actually do using Docile in the package then it should just work.

[zenna]

Ok, awesome, thanks.

[zenna]

Another issue: can't write docs with Lexicon

julia> using Lexicon

julia> save("docs/funcs.md", Sigma)
Docile: updating package list...
Docile: caching 1 module from 'Sigma'.
INFO: writing documentation to docs/funcs.md
ERROR: type cannot be constructed
 in generate_html_id at /home/zenna/.julia/v0.3/Lexicon/src/render.jl:217
 in prepare_entries at /home/zenna/.julia/v0.3/Lexicon/src/render.jl:153
 in mainsetup at /home/zenna/.julia/v0.3/Lexicon/src/render.jl:125
 in anonymous at /home/zenna/.julia/v0.3/Lexicon/src/render/md.jl:20
 in open at iostream.jl:137
 in save at /home/zenna/.julia/v0.3/Lexicon/src/render/md.jl:17
 in save at /home/zenna/.julia/v0.3/Lexicon/src/render.jl:165
 in save at /home/zenna/.julia/v0.3/Lexicon/src/render.jl:168

[MichaelHatherly]

Looks like a 0.4 Int constructor slipped through... sorry about that, should be a simple fix with @compat.

[MichaelHatherly]

Could you apply this diff and see if it works then?

diff --git a/src/render.jl b/src/render.jl
index d6ca1a5..2913b77 100644
--- a/src/render.jl
+++ b/src/render.jl
@@ -214,7 +214,7 @@ function generate_html_id(s::AbstractString)
         elseif c in replace_chars
             write(io, "_")
         else
-            write(io, string(Int(c)))
+            write(io, string(@compat(Int(c))))
         end
     end
     # Note: In our case no need to check for begins with letter or is empty

[zenna]

That seems to work!

[MichaelHatherly]

Cool, I'll tag a new release of Lexicon with that compat fix tomorrow morning then, thanks for testing that.

Re: the for-loop / include problem, trying to create a minimal test case hasn't succeeded so far:

module Sandbox

using Docile

for f in ["a.jl",
          "b.jl",
          "c.jl"]
    include(joinpath("files", f))
end

end

is loading fine and the contents of the subfiles are available. So no luck so far... perhaps it depends on the size of the package.

Have you overridden any methods from Base that could be related to file loading? The ambiguity warnings don't appear related, but it's possible they're could be triggering something else to cause it.

[MichaelHatherly]

The Lexicon fix is now in this tagged version.