Literate.jl: treat comments as comments

General Usage
1

In Literate, if I have code like

function foo(vec)
    # print the elements
    for x in vec
        print(x)
    end
end

Literate.markdown(; flavor=Literate.DocumenterFlavor()) will treat the comment as some separator, and output two @example blocks: one @example block containing just function foo(vec), then the comment in plain text, then another @example block containing the rest of the code. Then obviously Documenter chokes on it; neither block is syntactically correct. Is there any way around that? If I write my comment without a leading space, then it’s treated correctly, but it’s rather ugly.

Obviously, I’m happy to have top-level comments be treated as markdown. But comments inside of code blocks should be left as comments…

2

Lines marked with double ## will show up as „normal“ comments iirc.

Since #-lines are treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

3 Likes
3

It would be possible to make indented # comments be comments, but then that would be inconsistent with toplevel comments which would still have to be ## comments.

The reason for supporting indented # markdown is that Literate (and Documenter) supports splitting up expressions into incomplete parts. Here is an example input:

# This is the main function
function main()
    #+
    # First we call foo
    f = foo()
    #+
    # Then we call bar
    b = bar()
    #+
    # Finally we return the sum
    return f + b
end

with the markdown output:

This is the main function

````@example main; continued = true
function main()
````

First we call foo

````@example main; continued = true
    f = foo()
````

Then we call bar

````@example main; continued = true
    b = bar()
````

Finally we return the sum

````@example main
    return f + b
end
````

In version 1 of Literate the explicit continued-expression markers (#+) were optional, but since version 2 they are required so it would again be possible to require markdown to be dedented (but again, would be inconsistent with top level comments).

2 Likes