@ -5,12 +5,12 @@ to create a nice example for the documentation it is important that
@@ -5,12 +5,12 @@ to create a nice example for the documentation it is important that
the package maintainer does not feel limited by the by default provided syntax
that this package offers. While you can generally come a long way by utilizing
[line filtering](@ref Filtering-lines) there might be situations where you need
to manually hook into the generation and change things. In `Examples.jl` this
to manually hook into the generation and change things. In `Literate.jl` this
is done by letting the user supply custom pre- and post-processing functions
that may do transformation of the content.
All of the generators ([`Examples.markdown`](@ref), [`Examples.notebook`](@ref)
and [`Examples.script`](@ref)) accepts `preprocess` and `postprocess` keyword
All of the generators ([`Literate.markdown`](@ref), [`Literate.notebook`](@ref)
and [`Literate.script`](@ref)) accepts `preprocess` and `postprocess` keyword
arguments. The default "transformation" is the `identity` function. The input
to the transformation functions is a `String`, and the output should be the
transformed `String`.
@ -43,5 +43,5 @@ end
@@ -43,5 +43,5 @@ end
which would replace every occurrence of `"DATEOFTODAY"` with the current date. We would
now simply give this function to the generator, for example:
The source file format for `Examples.jl` is a regular, commented, julia (`.jl`) scripts.
The source file format for `Literate.jl` is a regular, commented, julia (`.jl`) scripts.
The idea is that the scripts also serve as documentation on their own and it is also
simple to include them in the test-suite, with e.g. `include`, to make sure the examples
stay up do date with other changes in your package.
@ -36,7 +36,7 @@ julia code. We note a couple of things:
@@ -36,7 +36,7 @@ julia code. We note a couple of things:
For simple use this is all you need to know, the script above is valid. Let's take a look
at what the above snippet would generate, with default settings:
- [`Examples.markdown`](@ref): leading `#'` are removed, and code lines are wrapped in
- [`Literate.markdown`](@ref): leading `#'` are removed, and code lines are wrapped in
`@example`-blocks:
````markdown
# Rational numbers
@ -56,7 +56,7 @@ at what the above snippet would generate, with default settings:
@@ -56,7 +56,7 @@ at what the above snippet would generate, with default settings:
```
````
- [`Examples.notebook`](@ref): leading `#'` are removed, markdown lines are placed in
- [`Literate.notebook`](@ref): leading `#'` are removed, markdown lines are placed in
`"markdown"` cells, and code lines in `"code"` cells:
```
│ # Rational numbers
@ -76,7 +76,7 @@ at what the above snippet would generate, with default settings:
@@ -76,7 +76,7 @@ at what the above snippet would generate, with default settings:
Out [2]: │ 11//15
```
- [`Examples.script`](@ref): all lines starting with `#'` are removed:
- [`Literate.script`](@ref): all lines starting with `#'` are removed:
```julia
x = 1//3
y = 2//5
@ -101,9 +101,9 @@ since `@docs` is Documenter syntax that the notebook will not understand. This
@@ -101,9 +101,9 @@ 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 #' Examples.markdown
#md #' Examples.notebook
#md #' Examples.markdown
#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
Welcome to the documentation for `Examples.jl`. A simplistic package
Welcome to the documentation for `Literate.jl`. A simplistic package
to help you organize examples for you package documentation.
### What?
`Examples.jl` is a package that, based on a single source file, generates markdown,
`Literate.jl` is a package that, based on a single source file, generates markdown,
for e.g. [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl),
[Jupyter notebooks](http://jupyter.org/) and uncommented scripts for documentation
of your package.
@ -15,20 +15,20 @@ be simple. In short all you have to do is to write a commented julia script!
@@ -15,20 +15,20 @@ be simple. In short all you have to do is to write a commented julia script!
The package consists mainly of three functions, which all takes the same script file
as input, but generates different output:
- [`Examples.markdown`](@ref): generates a markdown file
- [`Examples.notebook`](@ref): generates an (optionally executed) notebook
- [`Examples.script`](@ref): generates a plain script file, removing everything
- [`Literate.markdown`](@ref): generates a markdown file
- [`Literate.notebook`](@ref): generates an (optionally executed) notebook
- [`Literate.script`](@ref): generates a plain script file, removing everything
that is not code
### Why?
Examples are (probably) the best way to showcase your awesome package, and examples
Literate are (probably) the best way to showcase your awesome package, and examples
are often the best way for a new user to learn how to use it. It is therefore important
that the documentation of your package contains examples for users to read and study.
However, people are different, and we all prefer different ways of trying out a new
package. Some people wants to RTFM, others want to explore the package interactively in,
for example, a notebook, and some people wants to study the source code. The aim of
`Examples.jl` is to make it easy to give the user all of these options, while still
`Literate.jl` is to make it easy to give the user all of these options, while still
keeping maintenance to a minimum.
It is quite common that packages have "example notebooks" to showcase the package.
@ -42,8 +42,8 @@ by using [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) `@example`-
@@ -42,8 +42,8 @@ by using [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) `@example`-
This is also great, but it is not quite as interactive as a notebook, for the users
who prefer that.
`Examples.jl` tries to solve the problems above by creating the output as a part of the doc
build. `Examples.jl` generates the output from a single source file which makes it easier to
`Literate.jl` tries to solve the problems above by creating the output as a part of the doc
build. `Literate.jl` generates the output from a single source file which makes it easier to
maintain, test, and keep the manual and your example notebooks in sync.
Fredrik Ekre
8 years ago