Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Comments inside functions in scripts #258

Closed
moyner opened this issue Oct 15, 2024 · 2 comments
Closed

Comments inside functions in scripts #258

moyner opened this issue Oct 15, 2024 · 2 comments

Comments

@moyner
Copy link

moyner commented Oct 15, 2024

Thanks for this great package - I use it extensively in my documentation and it has been a joy to use!

I have a question on the intended behavior for comments inside functions.

Let us say that I have the following script:

# # Header
function myfunc(x)
    # This is a comment
    return x^2
end

If I run Literate.markdown("ex.jl") the output of the code itself is as follows

# Header

```@example ex
function myfunc(x)
```

This is a comment

```@example ex
    return x^2
end
```

(I replaced backticks with ' to make it render correctly)

Unfortunately this breaks the function evaluation since the Documenter parsing of examples assumes that each bit is a executable bit of code. Is this intended behavior, or is it a bug? I like to make commented functions in my scripts, but I see that this is maybe not the most typical use of literate programming.

@fredrikekre
Copy link
Owner

(I replaced backticks with ' to make it render correctly)

You can use more backticks on the outer block, so if the code block uses 4 backticks you can use blocks within with three backticks (see my edit).

See https://fredrikekre.github.io/Literate.jl/v2/fileformat/#Syntax:

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.

If I ever release Literate version 3 I think it would be smoother to requires the markdown-# to be the first character on the line.

@moyner
Copy link
Author

moyner commented Oct 17, 2024

Thanks! That makes sense - will use double comments in my helper functions 🙂

@moyner moyner closed this as completed Oct 17, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants