Documenter.jl: Linking to specific files and Documentation of Scripts

General Usage
,
1

I am currently writing a package and want to document everything from the beginning on. Documenter.jl is great for that.

I am currently writing and example script that also reproduces a previous result (from code in Matlab) but now in Julia. So I would like to have that as a standalone Script (standalone in the sense that: Having installed the Package I am working on it can just run without prior stuff).

I cam to two points, where I wondered: How do I do that in Julia (or Documenter)?

  1. Is there a possibility to provide a short description for a script file, like one does with the doc strings for functions? My idea is to provide the title and the main purpose of the script and maybe a reference where to get further informations

  2. I am accompanying the script by a illustrative page in the documentation and would like to link to the current (or maybe for older documentations even old versions) of a file in the repository. How can that be done in Documenter markdown?

1 Like
2

Sounds like you might find Literate.jl (ANN: Literate.jl) useful (disclaimer: I am the author of that package). Your usecase sounds just like the one I had for writing the package in the first place.

6 Likes
3

That is definitely a very nice way to pursue exactly my purpose.

Is the @REPO_ROOT_URLmaybe also directly available in Documenter or is that a feature of your package? The one reason I am asking is, that one of my result images I have in the documentation takes 10 hours to compute so it would be better to have that just in the documentation as a result and not computed (for example using an @example block in Documenter.

4

Today I tried to get the package running and I am already quite satisified – I added the following lines to the `make.jl´

tutorialsInputPath = joinpath(@__DIR__, "..", "src/tutorials")
tutorialsRelativePath = "tutorials/generated"
tutorialsOutputPath = joinpath(@__DIR__,"src/"*tutorialsRelativePath)
tutorials  = ["TutorialA,TutotialB"]
menuEntries = ["Menu Entry for Tutorial A", "Menu Entry for Tutorial B"]
TutorialMenu = Array{Pair{String,String},1}()
for (i,tutorial) in enumerate(tutorials)
    global TutorialMenu
    sourceFile = joinpath(tutorialsInputPath,tutorial*".jl")
    targetFile = joinpath(tutorialsOutputPath,tutorial*"md")
    Literate.markdown(sourceFile,tutorialsOutputPath; name=tutorial, credit=false)
    push!(TutorialMenu, menuEntries[i] => joinpath(tutorialsRelativePath,tutorial*".md") )
end

which enables to just add the line

        "Tutorials" => TutorialMenu,

to the menu of Documenter. That works great, though it would be nice to also have a check whether the example needs to be generated. Further, the meta link top left (which work locally in Documenter) won’t work when I compile the docs on my machine.

And I am not sure whether I encountered a bug but the lines

#md[`functionA`](@ref)s
#nb functionA
#. For a
#md[typeB](@ref)

I wanted to use to refer to functions and types in the documentation. However that gets translated in to a code block with

@example TutorialA
#md[`functionA`](@ref)s
#. For a
#md[typeB](@ref)

as content. I con’t understand why.
Edit: Now I do understand :wink: The #md just filters out but the following part of the line is still handled as Julia code, so pure markdown just used in markdown has to be prepended #md #.

The final thing I have to figure out is the jl format: Since all markdown and notebook “stuff” is commented, It should directly also run as a Julia script right? So the Julia processing would just remove a little bit of comments to make the src code file more readable?