ANN: Literate.jl


#1

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 JuAFEM.jl:

Feel free to try it out and please report any bugs/feature requests to the GitHub repo!

/Fredrik


#2

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 ?


#3

Cool.
Nice.

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.)


#4

Awesome, amazing @fredrikekre. I will put it to use as soon as I find some extra free time!!!


#5

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.


#6

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.

Should be trivial, just make sure you generate the files before you include them in test/runtests.jl. Notebooks can be tested with e.g. https://github.com/stevengj/NBInclude.jl


#7

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.


#8

But #' and ## isn’t far away.

I use Atom+Juno. There, I write something I can press a shortcut to comment it , (in my case ctr+1).

Is it hard to write a short cut that doesn’t simply add # but adds #' instead? If anybody knows how to do it please write it here as well :smiley:


#9

Yea, that is a nice option actually, if people prefer this I am open to change this, please chime in at https://github.com/fredrikekre/Literate.jl/issues/3


#10

What are the advantages of Literate over Weave here?


#11

The notebook output in 4.2. Notebook Output is just a mockup, it would produce a .ipynb file? Or is this actually a text-based .ipynb format?


#12

This should work for toggling #'s in Juno.


#13

As someone who absolutely despises using Jupyter notebooks, options like this are always highly welcome. Thanks for your work on this.

Seconding @tshort’s question, I have found Weave.jl to work quite well, so I’d be interested in a comparison between the two packages.


#14

Couldn’t the multi-line comments syntax resolve this issue?

#=
multiple lines of comment
blah blah blah
=#

If Literate could have a syntax like that, it would make things much easier.


#15

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):


#16

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!


#17

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

#18

Nope, but please open an issue and include a MWE!


#19

Will do, if I manage to boil it down to a MWE — my first attempts at this work just fine!


#20

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.