@ -27,8 +27,8 @@ We could of course update our source file before generating the docs, but we cou
@@ -27,8 +27,8 @@ We could of course update our source file before generating the docs, but we cou
instead use a `preprocess` function that splices the date into the source for us.
@ -8,25 +8,27 @@ stay up do date with other changes in your package.
@@ -8,25 +8,27 @@ stay up do date with other changes in your package.
## [**2.1.** Syntax](@id Syntax)
The basic syntax is simple:
- lines starting with `#'` is treated as markdown,
- lines starting with `# ` are treated as markdown,
- all other lines are treated as julia code.
The reason for using `#'` instead of `#` is that we want to be able to use `#` as comments,
just as in a regular script. Lets look at a simple example:
!!! note
If you want regular julia comments in the source file use `## ` instead of `# `.
Lets look at a simple example:
```julia
#' # Rational numbers
#'
#' In julia rational numbers can be constructed with the `//` operator.
#' Lets define two rational numbers, `x` and `y`:
# # Rational numbers
#
# In julia rational numbers can be constructed with the `//` operator.
# Lets define two rational numbers, `x` and `y`:
x = 1//3
y = 2//5
#' When adding `x` and `y` together we obtain a new rational number:
# When adding `x` and `y` together we obtain a new rational number:
z = x + y
```
In the lines `#'` we can use regular markdown syntax, for example the `#`
In the lines starting with `#` we can use regular markdown syntax, for example the `#`
used for the heading and the backticks for formatting code. The other lines are regular
julia code. We note a couple of things:
- The script is valid julia, which means that we can `include` it and the example will run
@ -60,11 +62,11 @@ using Documenter. Obviously we don't want to include this in the notebook,
@@ -60,11 +62,11 @@ using Documenter. Obviously we don't want to include this in the notebook,
since `@docs` is Documenter syntax that the notebook will not understand. This
is a case where we can prepend `#md` to those lines:
````julia
#md #' ```@docs
#md #' Literate.markdown
#md #' Literate.notebook
#md #' Literate.markdown
#md #' ```
#md # ```@docs
#md # Literate.markdown
#md # Literate.notebook
#md # Literate.markdown
#md # ```
````
The lines in the example above would be filtered out in the preprocessing step, unless we are
generating a markdown file. When generating a markdown file we would simple remove
@ -30,38 +30,38 @@ and mark them as either markdown or code according to the rules described in the
@@ -30,38 +30,38 @@ and mark them as either markdown or code according to the rules described in the
[Syntax](@ref Syntax) section. Lets consider the example from the previous section
with each line categorized:
```
#' # Rational numbers <-markdown
#'<-markdown
#' In julia rational numbers can be constructed with the `//` operator. <-markdown
#' Lets define two rational numbers, `x` and `y`: <-markdown
<-code
x = 1 // 3 <-code
y = 2 // 5 <-code
<-code
#' When adding `x` and `y` together we obtain a new rational number: <-markdown
<-code
z = x + y <-code
# # Rational numbers <-markdown
# <-markdown
# In julia rational numbers can be constructed with the `//` operator. <-markdown
# Lets define two rational numbers, `x` and `y`: <-markdown
<-code
x = 1 // 3 <-code
y = 2 // 5 <-code
<-code
# When adding `x` and `y` together we obtain a new rational number: <-markdown
<-code
z = x + y <-code
```
In the next step the lines are grouped into "chunks" of markdown and code.
This is done by simply collecting adjacent lines of the same "type" into
chunks:
```
#' # Rational numbers ┐
#' │
#' In julia rational numbers can be constructed with the `//` operator. │ markdown
#' Lets define two rational numbers, `x` and `y`: ┘
┐
x = 1 // 3 │
y = 2 // 5 │ code
┘
#' When adding `x` and `y` together we obtain a new rational number: ] markdown
┐
z = x + y ┘ code
# # Rational numbers ┐
# │
# In julia rational numbers can be constructed with the `//` operator. │ markdown
# Lets define two rational numbers, `x` and `y`: ┘
┐
x = 1 // 3 │
y = 2 // 5 │ code
┘
# When adding `x` and `y` together we obtain a new rational number: ] markdown
┐
z = x + y ┘ code
```
In the last parsing step all empty leading and trailing lines for each chunk
are removed, but empty lines *within the same* block are kept. The leading `#' `
are removed, but empty lines *within the same* block are kept. The leading `# `
tokens are also removed from the markdown chunks. Finally we would
end up with the following 4 chunks:
@ -112,7 +112,7 @@ The example above would result in two consecutive code-chunks.
@@ -112,7 +112,7 @@ The example above would result in two consecutive code-chunks.
After the parsing it is time to generate the output. What is done in this step is
very different depending on the output target, and it is describe in more detail in
the Output format sections: [Markdown Output](@ref), [Notebook Output](@ref) and
[Script Output](@ref). In short, the following is happening:
[Script Output](@ref). Using the default settings, the following is happening:
* Markdown output: markdown chunks are printed as-is, code chunks are put inside