Hello there,
I am happy to present Literate.jl, a lightweight package for literate programming. The main purpose is to facilitate writing Julia examples/tutorials that can be included in your package documentation.
I believe that one of the best way to showcase a package is to present well documented examples. However, people are different, and we all prefer different ways of trying out a new package. Some people want to RTFM, others want to explore the package interactively in a notebook, and some people want to study source code. The aim of Literate.jl is to make it easy to give the user all of these options, while still keeping maintenance to a minimum, by generating different output based on a single source-file.
Please take a look at the documentation for some more motivation of why I think you should use Literate.jl.
The best way to get a feel of the package is to look at an example (hehe). There is one example in the manual, but it is perhaps better to look at a real world example. Here is the source and the different outputs for an example of solving the heat equation from the manual of Ferrite.jl:
Looks great. Only issue is having all the #' at the beginning of each line, it doesn’t look very pleasant to edit. Wouldn’t it possible to use a string or something that looks a bit better ?
How easy is it to set it up so the generated script output is run during CI to make sure that it compiles still?
Actually i guess you don’t need to,
since the source code for the literate,jl is julia with all the literate comments, so one can just add that to the tests.
I might start using this.
I’ve gotten a bit grumpy about the complexity of making documentation lately and have kinda tended down the the lowest common demoninator.
just making markdown pages and putting them in /docs and linking to them from README.md.
This might be a nicer way to do it, and more testable and easier upgrade from later.
(and what I mean by the complexity of making documentation lately is remembering how to setup documentor.jl with travis.)
Also like the package a lot but am a bit puzzled by the #' choice as it’s easy to comment all the lines with most text editors, but I’m not sure what’s a easy way to toggle the #' sign at the beginning.
Well, one of the goals was that the source should be runable julia code (for example to make it simple to include as a test in the test suite), meaning that all metadata must be “guarded” behind comments, I opted for #' mostly because that is what Weave.jl uses. One option would be to use just # but it is nice to be able to use regular comments too. TBH it is not that annoying to edit.
I haven’t thought about it much, but using # for metadata and ## or similar for comments might work nicely – writing comments is probably less common than writing metadata. One could also then think about Literate.jl stripping the first # and interpreting the rest.
Yes of course, I have updated with a link to the actual notebook instead to make this clearer.
I tried out Weave before I wrote Literate. I simply found that it did not let me do the things I wanted. Here are some advantages with Literate (essentially the main reasons why I wrote the package in the first place):
Just a quick update for anyone interested:
There is now a new version released that uses # for markdown and ## for regular julia comments, as suggested by Sebastian above. Thanks for the feedback everyone!
This looks like exactly what I was looking for, many thanks!
I get the following warning about _show repeatedly – any clues about what this might mean?
Info: not running on Travis, skipping links will not be correct.
Info: executing notebook simple.ipynb
WARNING: _show is not defined for this backend. m=text/plain
I support the usage of #'. It won’t be annoying as long as the editor (e.g., atom) can recognize it as markdown texts instead of comments.
Edit: ## would be good too, but my main concern is that Juno may highlight it just as comments instead of regular texts. Although the compiler can read it, it would be difficult for us human beings to interpret.
