Documentation tips

Literate

• Write Julia comments with two # symbols, eg.

function foo(x, y)
    ## sum the arguments
    x + y
end

Including additional data files

Sometimes a model is defined by a binary file, eg jld. The file is stored in the same folder as the model, eg. /examples/Building. However, when Documenter runs the julia script generated by Literate, it is ran from a different folder. The current solution is to load the jld2 by navigating to its location from the julia script.

current method:

# in file examples/Building/Building.jl
examples_dir = normpath(@__DIR__, "..", "..", "..", "examples")
building_path = joinpath(examples_dir, "Building", "building.jld2")

other ideas:

joinpath(dirname(dirname(@__FILE__), "examples/building.jld2")
joinpath(@__DIR__, "building.jld2")
normpath(joinpath(@__DIR__, "..", parts...))