# Literate.jl announcement

**URL:** <https://discourse.julialang.org/t/literate-jl-announcement/10651>\
**Category:** Package Announcements\
**Created:** [May 2, 2018, 9:31am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651 "2018-05-02T09:31:09Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [May 2, 2018, 9:31am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/1 "2018-05-02T09:31:09Z")

</div>

Hello there,  
I am happy to present [Literate.jl](https://github.com/fredrikekre/Literate.jl), a lightweight package for [literate programming](https://en.wikipedia.org/wiki/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](https://fredrikekre.github.io/Literate.jl/) 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](https://fredrikekre.github.io/Literate.jl/latest/generated/example/), 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](https://github.com/Ferrite-FEM/Ferrite.jl):

- [Source code](https://github.com/Ferrite-FEM/Ferrite.jl/blob/master/docs/src/literate/heat_equation.jl)
- [Markdown output](https://ferrite-fem.github.io/Ferrite.jl/stable/examples/heat_equation/)
- [Notebook output](https://nbviewer.org/github/Ferrite-FEM/Ferrite.jl/blob/gh-pages/v0.3.1/examples/heat_equation.ipynb)
- [Script output](https://github.com/Ferrite-FEM/Ferrite.jl/blob/gh-pages/v0.3.1/examples/heat_equation.jl)

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

/Fredrik

---

<div class="post-metadata">

**Author:** ![jonathanBieler](https://avatars.discourse-cdn.com/v4/letter/j/82dd89/32.png) [@jonathanBieler](https://discourse.julialang.org/u/jonathanBieler)\
**Post date:** [May 2, 2018, 10:00am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/2 "2018-05-02T10:00:37Z")

</div>

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 ?

---

<div class="post-metadata">

**Author:** ![oxinabox](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/oxinabox/32/206603_2.png) [@oxinabox](https://discourse.julialang.org/u/oxinabox)\
**Post date:** [May 2, 2018, 10:01am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/3 "2018-05-02T10:01:08Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Datseris](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/datseris/32/13406_2.png) [@Datseris](https://discourse.julialang.org/u/Datseris)\
**Post date:** [May 2, 2018, 10:13am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/4 "2018-05-02T10:13:15Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![piever](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/piever/32/1815_2.png) [@piever](https://discourse.julialang.org/u/piever)\
**Post date:** [May 2, 2018, 10:15am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/5 "2018-05-02T10:15:22Z")

</div>

> [@oxinabox](#):
>
> t 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.

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.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [May 2, 2018, 10:19am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/6 "2018-05-02T10:19:59Z")

</div>

> [@jonathanBieler](#):
>
> 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 ?

> [@piever](#):
>
> 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](https://github.com/mpastell/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.

> [@oxinabox](#):
>
> How easy is it to set it up so the generated script output is run during CI to make sure that it compiles still?

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. [GitHub - JuliaInterop/NBInclude.jl: import code from IJulia Jupyter notebooks into Julia programs](https://github.com/stevengj/NBInclude.jl)

---

<div class="post-metadata">

**Author:** ![pfitzseb](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/pfitzseb/32/45566_2.png) [@pfitzseb](https://discourse.julialang.org/u/pfitzseb)\
**Post date:** [May 2, 2018, 10:24am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/7 "2018-05-02T10:24:51Z")

</div>

> [@fredrikekre](#):
>
> One option would be to use just # but it is nice to be able to use regular comments too.

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.

---

<div class="post-metadata">

**Author:** ![Datseris](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/datseris/32/13406_2.png) [@Datseris](https://discourse.julialang.org/u/Datseris)\
**Post date:** [May 2, 2018, 10:28am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/8 "2018-05-02T10:28:11Z")

</div>

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 😃

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [May 2, 2018, 10:54am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/9 "2018-05-02T10:54:32Z")

</div>

> [@pfitzseb](#):
>
> using # for metadata and ## or similar for comments might work nicely

Yea, that is a nice option actually, if people prefer this I am open to change this, please chime in at [Change `#'` to simply `#` and require `##` for julia comments · Issue #3 · fredrikekre/Literate.jl · GitHub](https://github.com/fredrikekre/Literate.jl/issues/3)

---

<div class="post-metadata">

**Author:** ![tshort](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tshort/32/43_2.png) [@tshort](https://discourse.julialang.org/u/tshort)\
**Post date:** [May 2, 2018, 11:36am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/10 "2018-05-02T11:36:47Z")

</div>

What are the advantages of Literate over Weave here?

---

<div class="post-metadata">

**Author:** ![mschauer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mschauer/32/13946_2.png) [@mschauer](https://discourse.julialang.org/u/mschauer)\
**Post date:** [May 2, 2018, 11:38am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/11 "2018-05-02T11:38:00Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![pfitzseb](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/pfitzseb/32/45566_2.png) [@pfitzseb](https://discourse.julialang.org/u/pfitzseb)\
**Post date:** [May 2, 2018, 12:22pm UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/12 "2018-05-02T12:22:18Z")

</div>

[This](https://gist.github.com/pfitzseb/b8ab0b4d5008b69e92a02df6a97d8f0c) should work for toggling `#'`s in Juno.

---

<div class="post-metadata">

**Author:** ![ExpandingMan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/expandingman/32/866_2.png) [@ExpandingMan](https://discourse.julialang.org/u/ExpandingMan)\
**Post date:** [May 2, 2018, 1:41pm UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/13 "2018-05-02T13:41:51Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![chakravala](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/chakravala/32/6832_2.png) [@chakravala](https://discourse.julialang.org/u/chakravala)\
**Post date:** [May 2, 2018, 2:46pm UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/14 "2018-05-02T14:46:39Z")

</div>

> [@jonathanBieler](#):
>
> Only issue is having all the #’ at the beginning of each line, it doesn’t look very pleasant to edit.

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

```Julia
#=
multiple lines of comment
blah blah blah
=#

```

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

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [May 2, 2018, 3:04pm UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/15 "2018-05-02T15:04:20Z")

</div>

> [@mschauer](#):
>
> The notebook output in 4.2. Notebook Output is just a mockup, it would produce a .ipynb file?

Yes of course, I have updated with a link to the actual notebook instead to make this clearer.

> [@tshort](#):
>
> What are the advantages of Literate over Weave here?

> [@ExpandingMan](#):
>
> I have found Weave.jl to work quite well, so I’d be interested in a comparison between the two packages.

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

- Literate makes it easier for the user to hook into the generation. This means that you are not locked by the syntax/features that Literate offers, you can do your own custom source transformations. I think this is important, since all packages are different, and all users have different things they want to do, and all these features can not be in the package. Real life example: [https://github.com/KristofferC/JuAFEM.jl/blob/13a51cc4c3d11da64fb34ed1ea96e35739a42f6b/docs/generate.jl#L11-L13](https://github.com/KristofferC/JuAFEM.jl/blob/13a51cc4c3d11da64fb34ed1ea96e35739a42f6b/docs/generate.jl#L11-L13) where the custom `postprocess` function dumps the result of the `Literate.script` output into the markdown file, to include the source in the last section: [http://kristofferc.github.io/JuAFEM.jl/latest/examples/generated/heat\_equation.html#heat\_equation-plain-program-1](http://kristofferc.github.io/JuAFEM.jl/latest/examples/generated/heat_equation.html#heat_equation-plain-program-1)
- Filtering of lines: Literate filters some lines based on the output, see [https://fredrikekre.github.io/Literate.jl/latest/fileformat.html#Filtering-Lines-1](https://fredrikekre.github.io/Literate.jl/latest/fileformat.html#Filtering-Lines-1). This is very convenient and you can for example add things like [https://github.com/KristofferC/JuAFEM.jl/blob/13a51cc4c3d11da64fb34ed1ea96e35739a42f6b/docs/src/examples/heat\_equation.jl#L5-L7](https://github.com/KristofferC/JuAFEM.jl/blob/13a51cc4c3d11da64fb34ed1ea96e35739a42f6b/docs/src/examples/heat_equation.jl#L5-L7) which you probably don’t want in the notebook output.
- Better integration with Documenter.jl: You can use Documenter-style `@ref` and `@id` without this leaking out to the notebook/script outputs.
- Literate is more lightweight since it does not contain all the machinery to generate html/pdf etc.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [May 7, 2018, 9:19am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/16 "2018-05-07T09:19:02Z")

</div>

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!

---

<div class="post-metadata">

**Author:** ![improbable22](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/improbable22/32/5464_2.png) [@improbable22](https://discourse.julialang.org/u/improbable22)\
**Post date:** [May 7, 2018, 3:54pm UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/17 "2018-05-07T15:54:49Z")

</div>

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?

```julia
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

```

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [May 7, 2018, 4:33pm UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/18 "2018-05-07T16:33:06Z")

</div>

> [@improbable22](#):
>
> I get the following warning about \_show repeatedly – any clues about what this might mean?

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

---

<div class="post-metadata">

**Author:** ![improbable22](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/improbable22/32/5464_2.png) [@improbable22](https://discourse.julialang.org/u/improbable22)\
**Post date:** [May 7, 2018, 8:36pm UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/19 "2018-05-07T20:36:36Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Wenjie](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/wenjie/32/10123_2.png) [@Wenjie](https://discourse.julialang.org/u/Wenjie)\
**Post date:** [May 14, 2018, 9:45am UTC](https://discourse.julialang.org/t/literate-jl-announcement/10651/20 "2018-05-14T09:45:19Z")

</div>

> [@fredrikekre](#):
>
> 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 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.

[Next page](https://discourse.julialang.org/t/literate-jl-announcement/10651.md?page=2)