[bug] generation of documentation freezes

jorgepz commented 2 years ago

Bug description

the process of generation of the documentation freezes in ubuntu and in arch. the build folder is not filled with the files. only image files are copied to assets and applications folder

Minimum (non-)working example

(@v1.7) pkg> activate .
  Activating project at `~/work/IntervalLinearAlgebra.jl`

julia> include("docs/make.jl")
[ Info: generating markdown page from `~/work/IntervalLinearAlgebra.jl/docs/literate/applications/FEM_example.jl`
[ Info: writing result to `~/work/IntervalLinearAlgebra.jl/docs/src/applications/FEM_example.md`
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.

Expected behavior

documentation html files generated in the build folder.

Version info

(IntervalLinearAlgebra) pkg> st
     Project IntervalLinearAlgebra v0.1.4
      Status `~/work/IntervalLinearAlgebra.jl/Project.toml`
  [38540f10] CommonSolve v0.2.0
  [d1acc4aa] IntervalArithmetic v0.20.3
  [189a3867] Reexport v1.2.2
  [ae029012] Requires v1.3.0
  [90137ffa] StaticArrays v1.3.3
  [37e2e46d] LinearAlgebra

julia> versioninfo()
Julia Version 1.7.0
Commit 3bf9d17731 (2021-11-30 12:12 UTC)
Platform Info:
  OS: Linux (x86_64-pc-linux-gnu)
  CPU: Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz

lucaferranti commented 2 years ago

I cannot reproduce this, it works fine for me (tested on windows and ubuntu. You are calling include("docs/make.jl"). By the printed log, it seems you have Documenter and Literate installed in your main environment, so that's probably not the problem.

What version of Documenter are you using? Was the problem that the generated build folder is empty or that it takes forever and never generates it? If it's the former, it almost sounds like Documenter doesn't have the rights to write in that folder 🤔 are you using your own computer or some university computer in the university network?

jorgepz commented 2 years ago

The versions of what is installed in the main environment are

(@v1.7) pkg> st
      Status `~/.julia/environments/v1.7/Project.toml`
  [e30172f5] Documenter v0.27.12
  [b4f0291d] LazySets v1.53.4
  [98b081ad] Literate v2.10.0
  [91a5bcdd] Plots v1.25.6
  [56ddb016] Logging

the folder structure of the build folder is generated buy only svg and png images are copied there....

jorge@iet47:~/work/IntervalLinearAlgebra.jl$ ls docs/build/
api  applications  assets  explanations  tutorials
jorge@iet47:~/work/IntervalLinearAlgebra.jl$ ls docs/build/api/
jorge@iet47:~/work/IntervalLinearAlgebra.jl$ ls docs/build/assets/
3dexample.png  logo.svg  logo-text.svg  quickstart.png  trussDiagram.svg
jorge@iet47:~/work/IntervalLinearAlgebra.jl$ ls docs/build/applications/
deformed.png
jorge@iet47:~/work/IntervalLinearAlgebra.jl$ ls docs/build/explanations/
jorge@iet47:~/work/IntervalLinearAlgebra.jl$ ls docs/build/tutorials/
jorge@iet47:~/work/IntervalLinearAlgebra.jl$

I tested in Windows 10 and was able to generate the docs!

I have admin privileges in the computers I am using.

I think that the debugger might help... i made an execution using some commands from https://docs.julialang.org/en/v1/stdlib/Logging/ this is the output (sorry for the extension 😅 )

(@v1.7) pkg> activate .
  Activating project at `~/work/IntervalLinearAlgebra.jl`

(IntervalLinearAlgebra) pkg> instantiate

julia> using Logging

julia> debuglogger = ConsoleLogger(stderr, Logging.Debug)
ConsoleLogger(Base.TTY(RawFD(15) open, 0 bytes waiting), Debug, Logging.default_metafmt, true, 0, Dict{Any, Int64}())

julia> with_logger(debuglogger) do
                  @debug include("docs/make.jl")
           end
┌ Debug: GR Binaries:
│   GR.gr_provider[] = "BinaryBuilder"
│   GR.libGR = "libGR.so"
│   GR.libGR3 = "libGR3.so"
│   GR.libGRM = "libGRM.so"
└ @ GR ~/.julia/packages/GR/KPElO/src/GR.jl:322
[ Info: generating markdown page from `~/work/IntervalLinearAlgebra.jl/docs/literate/applications/FEM_example.jl`
[ Info: writing result to `~/work/IntervalLinearAlgebra.jl/docs/src/applications/FEM_example.md`
┌ Debug: Creating documentation metadata dictionary (META=##docmeta#274) in IntervalLinearAlgebra
└ @ Documenter.DocMeta ~/.julia/packages/Documenter/Nu7Lp/src/DocMeta.jl:36
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
┌ Debug: Running doctests.
└ @ Documenter.DocTests ~/.julia/packages/Documenter/Nu7Lp/src/DocTests.jl:47
[ Info: ExpandTemplates: expanding markdown templates.
┌ Debug: pages
│   keys(doc.blueprint.pages) =
│    KeySet for a Dict{String, Documenter.Documents.Page} with 15 entries. Keys:
│      "references.md"
│      "api/eigenvalues.md"
│      "api/precondition.md"
│      "applications/FEM_example.md"
│      "explanations/preconditioning.md"
│      "CONTRIBUTING.md"
│      "tutorials/linear_systems.md"
│      "api/misc.md"
│      ⋮
│   priority_pages = String[]
│   normal_pages =
│    15-element Vector{String}:
│     "CONTRIBUTING.md"
│     "api/algorithms.md"
│     "api/classify.md"
│     "api/eigenvalues.md"
│     ⋮
│     "index.md"
│     "references.md"
│     "tutorials/eigenvalues.md"
│     "tutorials/linear_systems.md"
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:36
┌ Debug: Running ExpanderPipeline on CONTRIBUTING.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:39
┌ Debug: Running ExpanderPipeline on api/algorithms.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:39
┌ Debug: Evaluating @docs block:
│ GaussianElimination
│ HansenBliekRohn
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:279
┌ Debug: Evaluating @docs block:
│ GaussSeidel
│ Jacobi
│ LinearKrawczyk
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:279
┌ Debug: Evaluating @docs block:
│ LinearOettliPrager
│ NonLinearOettliPrager
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:279
┌ Debug: Evaluating @docs block:
│ Skalna06
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:279
┌ Debug: Running ExpanderPipeline on api/classify.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:39
┌ Debug: Evaluating @autodocs block:
│ Modules=[IntervalLinearAlgebra]
│ Pages = ["classify.jl"]
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:376
┌ Debug: Running ExpanderPipeline on api/eigenvalues.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:39
┌ Debug: Evaluating @autodocs block:
│ Modules=[IntervalLinearAlgebra]
│ Pages=["interval_eigenvalues.jl"]
│ Private=false
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:376
┌ Debug: Evaluating @autodocs block:
│ Modules=[IntervalLinearAlgebra]
│ Pages=["verify_eigs.jl"]
│ Private=false
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:376
┌ Debug: Running ExpanderPipeline on api/epsilon_inflation.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:39
┌ Debug: Evaluating @autodocs block:
│ Modules = [IntervalLinearAlgebra]
│ Pages = ["linear_systems/verify.jl"]
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:376
┌ Debug: Running ExpanderPipeline on api/misc.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:39
┌ Debug: Evaluating @docs block:
│ set_multiplication_mode
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:279
┌ Debug: Evaluating @docs block:
│ @affinevars
│ AffineExpression
│ AffineParametricArray
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:279
┌ Debug: Evaluating @autodocs block:
│ Modules = [IntervalLinearAlgebra]
│ Pages = ["utils.jl", "rref.jl"]
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:376
┌ Debug: Running ExpanderPipeline on api/precondition.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:39
┌ Debug: Evaluating @autodocs block:
│ Modules=[IntervalLinearAlgebra]
│ Pages=["precondition.jl"]
│ Private=false
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:376
┌ Debug: Running ExpanderPipeline on api/solve.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:39
┌ Debug: Evaluating @docs block:
│ solve
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:279
┌ Debug: Running ExpanderPipeline on applications/FEM_example.md
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:39
┌ Debug: Evaluating @meta block:
│ EditURL = "<unknown>/docs/literate/applications/FEM_example.jl"
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:253
┌ Debug: Evaluating @example block:
│ function unitaryStiffnessMatrix( coordFirstNode, coordSecondNode  )
│   diff      = (coordSecondNode - coordFirstNode)
│   length   = sqrt( diff' * diff )
│   c        = diff[1] / length
│   s        = diff[2] / length
│   Qloc2glo = [ c -s 0 0 ; s c 0 0 ; 0 0 c -s ; 0 0 s c ]
│   Kloc     = [ 1 0 -1 0 ; 0 0 0 0 ; -1 0 1 0 ; 0 0 0 0 ]
│   Kglo     = Qloc2glo * Kloc * transpose(Qloc2glo)
│   return     Kglo, length
│ end
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:566
┌ Debug: Evaluating @example block:
│ E = 2e11 ; # Young modulus
│ A = 5e-3 ; # Cross-section area
│ nothing #hide
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:566
┌ Debug: Evaluating @example block:
│ nodesCMatrix = [ 0.0 0.0 ;
│                  1.0 1.0 ;
│                  2.0 0.0 ;
│                  3.0 1.0 ;
│                  4.0 0.0 ];
│ nothing #hide
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:566
┌ Debug: Evaluating @example block:
│ connecMatrix = [ 1     2 ;
│                  1     3 ;
│                  2     3 ;
│                  2     4 ;
│                  3     4 ;
│                  3     5 ;
│                  4     5 ];
│ nothing #hide
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:566
┌ Debug: Evaluating @example block:
│ fixedDofs = [ 2 9 10 ];
│ nothing #hide
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:566
┌ Debug: Evaluating @example block:
│ numNodes = size( nodesCMatrix )[1]  # compute the number of nodes
│ numElems = size( connecMatrix )[1]  # compute the number of elements
│ freeDofs = zeros(Int8, 2*numNodes-length(fixedDofs))
│ indDof  = 1 ; counter = 0
│ while indDof <= (2*numNodes)
│   if !(indDof in fixedDofs)
│     global counter = counter + 1
│     freeDofs[ counter ] = indDof
│   end
│   global indDof = indDof + 1
│ end
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:566
┌ Debug: Evaluating @example block:
│ KG = zeros( 2*numNodes, 2*numNodes )
│ FG = zeros( 2*numNodes )
│ for elem in 1:numElems
│   indexFirstNode  = connecMatrix[ elem, 1 ]
│   indexSecondNode = connecMatrix[ elem, 2 ]
│   dofsElem = [2*indexFirstNode-1 2*indexFirstNode 2*indexSecondNode-1 2*indexSecondNode ]
│   KGelem, lengthElem = unitaryStiffnessMatrix( nodesCMatrix[ indexSecondNode, : ], nodesCMatrix[ indexFirstNode, : ] )
│   stiffnessParam = E * A / lengthElem
│   for i in 1:4
│     for j in 1:4
│       KG[ dofsElem[i], dofsElem[j] ] = KG[ dofsElem[i], dofsElem[j] ] + stiffnessParam * KGelem[i,j]
│     end
│   end
│ end
│ FG[4] = -1e4 ;
│ KG = KG[ freeDofs, : ]
│ KG = KG[ :, freeDofs ]
│ FG = FG[ freeDofs ]
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:566
┌ Debug: Evaluating @example block:
│ u = KG \ FG
│ UG = zeros( 2*numNodes )
│ UG[ freeDofs ] = u
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:566
┌ Debug: Evaluating @example block:
│ using Plots
│ scaleFactor = 2e3
│ plot();
│ for elem in 1:numElems
│   indexFirstNode  = connecMatrix[ elem, 1 ];
│   indexSecondNode = connecMatrix[ elem, 2 ];
│   # plot reference element
│   plot!( nodesCMatrix[ [indexFirstNode, indexSecondNode], 1 ],
│          nodesCMatrix[ [indexFirstNode, indexSecondNode], 2 ],
│          linestyle = :dash,  aspect_ratio = :equal,
│          linecolor = "blue", legend = false)
│ 
│   # plot deformed element
│   plot!( nodesCMatrix[ [indexFirstNode, indexSecondNode], 1 ]
│            + scaleFactor* [ UG[indexFirstNode*2-1], UG[indexSecondNode*2-1]] ,
│          nodesCMatrix[ [indexFirstNode, indexSecondNode], 2 ]
│            + scaleFactor* [ UG[indexFirstNode*2  ], UG[indexSecondNode*2  ]] , markershape = :circle, aspect_ratio = :equal, linecolor = "red",
│            linewidth=1.5, legend = false )
│ end
│ xlabel!("x (m)") # hide
│ ylabel!("y (m)") # hide
│ title!( "Deformed with scale factor " * string(scaleFactor) ) # hide
│ savefig("deformed.png") # hide
└ @ Documenter.Expanders ~/.julia/packages/Documenter/Nu7Lp/src/Expanders.jl:566

lucaferranti commented 2 years ago

it seems to me that it generates the docstrings and markdown from literate script successfully? Does it continue?

jorgepz commented 2 years ago

I does not continue... just stays frozen there...

I just tested the generation of ONSAS documentation https://github.com/ONSAS/ONSAS.m/ (using documenter) and it works fine

julia> include("docs/make.jl")
[ Info: Precompiling ONSAS_docs [top-level]
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Warning: Documenter could not auto-detect the building environment Skipping deployment.
└ @ Documenter ~/.julia/packages/Documenter/Nu7Lp/src/deployconfig.jl:75

julia>

jorgepz commented 2 years ago

it seems to me that it generates the docstrings and markdown from literate script successfully? Does it continue?

yes! the markdown files are generated. they are in the docs/src folder

lucaferranti commented 2 years ago

can you run the FEM_example.jl as a normal julia script, like does that code compile. I am asking because it seems it doesn't generate the images from the second example (the continuous example with 450 nodes)

jorgepz commented 2 years ago

eureka!

I ran the script and got this error

julia> include("docs/literate/applications/FEM_example.jl")
ERROR: LoadError: UndefVarError: @md_str not defined
Stacktrace:
 [1] top-level scope
   @ :0
 [2] include(fname::String)
   @ Base.MainInclude ./client.jl:451
 [3] top-level scope
   @ REPL[5]:1
in expression starting at /home/jor/work/jorgepz/IntervalLinearAlgebra.jl/docs/literate/applications/FEM_example.jl:167
in expression starting at /home/jor/work/jorgepz/IntervalLinearAlgebra.jl/docs/literate/applications/FEM_example.jl:167

then removed the md"" comments. ran again the docs/make.jl and it works!

lucaferranti commented 2 years ago

mmm weird, the md""" comments didn't work on Windows but did work on Linux, then I opened this issue and it was fixed after that. Also, I just noticed that you have Literate 2.10, I have 2.9, I'll try to update my literate and see if it breaks the docs. If it does, it's probably a Literate (or Literate+Documenter) issue

lucaferranti commented 2 years ago

yes it works with Literate 2.10 on windows. It also works with Julia 1.6 on WSL, so it might be a julia 1.7 issue or Literate issue

jorgepz commented 2 years ago

Now using Literate 2.11.0 the results are the same in windows and linux. I used the test file from https://github.com/fredrikekre/Literate.jl/issues/171 There is an error when including the script but when using Markdown there are no errors...

julia> using Literate    

julia> include("test_file.jl")
ERROR: LoadError: UndefVarError: @md_str not defined
Stacktrace:
  [1] top-level scope                                                                                                                                                         
    @ :0                                                                                                                                                                      
  [2] include(fname::String)                                                                                                                                               
    @ Base.MainInclude .\client.jl:451                                                                                                                                        
  [3] top-level scope                                                                                                                                                         
    @ REPL[5]:1                                                                                                                                                              
    in expression starting at C:\Users\jor\Desktop\test_file.jl:1                                                                                                          
    in expression starting at C:\Users\jor\Desktop\test_file.jl:1                                                                                                                                                                                                                                                                                 
julia> using Markdown         

julia> include("test_file.jl")     
3                                        
v1.7) pkg> st 
Status `C:\Users\jor\.julia\environments\v1.7\Project.toml` 
[e30172f5] Documenter v0.27.12 
[b4f0291d] LazySets v1.53.4 
[98b081ad] Literate v2.11.0 
[91a5bcdd] Plots v1.25.7

regarding the documentation generation, now that markdown blocks are defined not using md""" I was able to generate the html both in windows and linux 💯

JuliaIntervals / IntervalLinearAlgebra.jl