105 lines
2.2 KiB
Markdown
105 lines
2.2 KiB
Markdown
|
@def hascode = true
|
||
|
|
@def showall = true
|
||
|
|
@def hasmath = true
|
||
|
|
|
||
|
|
# Work with Literate.jl
|
||
|
|
|
||
|
|
\blurb{Franklin works seamlessly with Literate to offer a convenient way to write and maintain tutorials.}
|
||
|
|
|
||
|
|
\lineskip
|
||
|
|
|
||
|
|
\toc
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
[Literate.jl](https://github.com/fredrikekre/Literate.jl) is a convenient package that allows you to write scripts in Julia and convert them to markdown pages or Jupyter notebooks.
|
||
|
|
|
||
|
|
You can combine this with Franklin with the `\literate` command which you can call in Franklin like:
|
||
|
|
|
||
|
|
```
|
||
|
|
\literate{/_literate/script.jl}
|
||
|
|
```
|
||
|
|
|
||
|
|
it does what you expect:
|
||
|
|
|
||
|
|
@@tlist
|
||
|
|
* the markdown is interpreted and evaluated
|
||
|
|
* the code blocks are evaluated and their output can be shown selectively
|
||
|
|
@@
|
||
|
|
|
||
|
|
If you want the script to be shown like a notebook where the output of every code block is shown, use `@def showall = true`.
|
||
|
|
|
||
|
|
Combining Franklin with Literate offers a very convenient way to write and maintain tutorial websites (see for instance the [MLJ Tutorials](https://alan-turing-institute.github.io/MLJTutorials/)).
|
||
|
|
|
||
|
|
### File organisation
|
||
|
|
|
||
|
|
We recommend you have a folder `/_literate/` in your root folder, place your literate scripts there and call them as in the example above.
|
||
|
|
|
||
|
|
### Tricks
|
||
|
|
|
||
|
|
In the `showall = true` mode, the last line of each code block is displayed in full.
|
||
|
|
In some cases you will have to think about this a bit more than you would in your REPL and might for instance:
|
||
|
|
|
||
|
|
@@tlist
|
||
|
|
* _suppress the output_, in which case you should add a `;` at the end of the line
|
||
|
|
* _only show a few elements_ (see below)
|
||
|
|
@@
|
||
|
|
|
||
|
|
For instance you might prefer:
|
||
|
|
|
||
|
|
```julia:ee0
|
||
|
|
x = randn(10)
|
||
|
|
x[1:3]
|
||
|
|
```
|
||
|
|
|
||
|
|
to just
|
||
|
|
|
||
|
|
```julia:ee1
|
||
|
|
x = randn(10)
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also use `@show` or `println` to show specific things beyond the last line
|
||
|
|
|
||
|
|
```julia:ee2
|
||
|
|
x = rand(10)
|
||
|
|
println(sum(x))
|
||
|
|
y = 5
|
||
|
|
```
|
||
|
|
|
||
|
|
if the last line is a `@show` or `print` then only that is shown:
|
||
|
|
|
||
|
|
```julia:ee3
|
||
|
|
x = randn(10)
|
||
|
|
@show x[1]
|
||
|
|
```
|
||
|
|
|
||
|
|
## Example
|
||
|
|
|
||
|
|
### Script
|
||
|
|
|
||
|
|
`````julia
|
||
|
|
# Some **really cool** maths:
|
||
|
|
#
|
||
|
|
# $$ \exp(i\pi) + 1 \quad = \quad 0 $$
|
||
|
|
#
|
||
|
|
# We can show this with some code:
|
||
|
|
|
||
|
|
x = exp(im*π) + 1
|
||
|
|
|
||
|
|
# that looks close to zero but
|
||
|
|
|
||
|
|
x ≈ 0
|
||
|
|
|
||
|
|
# however
|
||
|
|
|
||
|
|
abs(x) < eps()
|
||
|
|
|
||
|
|
# #### Conclusion
|
||
|
|
#
|
||
|
|
# The equation is proven thanks to our very rigorous proof.
|
||
|
|
`````
|
||
|
|
|
||
|
|
### Result
|
||
|
|
|
||
|
|
\literate{/_literate/script_ee.jl} <!--_-->
|