From 7873977d4cd99750e12345f9ef7beff78469d716 Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Thu, 10 Jun 2021 18:43:21 +0200 Subject: [PATCH] Add outdated warning. --- v0.1.0/customprocessing.html | 51 +++++++- v0.1.0/documenter.html | 53 +++++++- v0.1.0/fileformat.html | 65 ++++++++-- v0.1.0/generated/example.html | 51 +++++++- v0.1.0/index.html | 45 ++++++- v0.1.0/outputformats.html | 61 +++++++-- v0.1.0/pipeline.html | 69 ++++++++-- v0.1.0/search.html | 45 ++++++- v0.2.0/customprocessing.html | 49 ++++++- v0.2.0/documenter.html | 53 +++++++- v0.2.0/fileformat.html | 49 ++++++- v0.2.0/generated/example.html | 51 +++++++- v0.2.0/index.html | 45 ++++++- v0.2.0/outputformats.html | 53 +++++++- v0.2.0/pipeline.html | 51 +++++++- v0.2.0/search.html | 45 ++++++- v0.2.1/customprocessing.html | 49 ++++++- v0.2.1/documenter.html | 53 +++++++- v0.2.1/fileformat.html | 49 ++++++- v0.2.1/generated/example.html | 51 +++++++- v0.2.1/index.html | 45 ++++++- v0.2.1/outputformats.html | 53 +++++++- v0.2.1/pipeline.html | 51 +++++++- v0.2.1/search.html | 45 ++++++- v0.2.2/customprocessing.html | 49 ++++++- v0.2.2/documenter.html | 53 +++++++- v0.2.2/fileformat.html | 49 ++++++- v0.2.2/generated/example.html | 188 +++++++++++---------------- v0.2.2/index.html | 45 ++++++- v0.2.2/outputformats.html | 53 +++++++- v0.2.2/pipeline.html | 51 +++++++- v0.2.2/search.html | 45 ++++++- v0.3.0/customprocessing.html | 49 ++++++- v0.3.0/documenter.html | 53 +++++++- v0.3.0/fileformat.html | 49 ++++++- v0.3.0/generated/example.html | 188 +++++++++++---------------- v0.3.0/index.html | 45 ++++++- v0.3.0/outputformats.html | 53 +++++++- v0.3.0/pipeline.html | 51 +++++++- v0.3.0/search.html | 45 ++++++- v1.0.0/customprocessing.html | 49 ++++++- v1.0.0/documenter.html | 53 +++++++- v1.0.0/fileformat.html | 49 ++++++- v1.0.0/generated/example.html | 188 +++++++++++---------------- v1.0.0/index.html | 45 ++++++- v1.0.0/outputformats.html | 53 +++++++- v1.0.0/pipeline.html | 51 +++++++- v1.0.0/search.html | 45 ++++++- v1.0.1/customprocessing.html | 49 ++++++- v1.0.1/documenter.html | 53 +++++++- v1.0.1/fileformat.html | 49 ++++++- v1.0.1/generated/example.html | 188 +++++++++++---------------- v1.0.1/index.html | 45 ++++++- v1.0.1/outputformats.html | 53 +++++++- v1.0.1/pipeline.html | 51 +++++++- v1.0.1/search.html | 45 ++++++- v1.0.2/customprocessing.html | 49 ++++++- v1.0.2/documenter.html | 53 +++++++- v1.0.2/fileformat.html | 49 ++++++- v1.0.2/generated/example.html | 188 +++++++++++---------------- v1.0.2/index.html | 45 ++++++- v1.0.2/outputformats.html | 53 +++++++- v1.0.2/pipeline.html | 51 +++++++- v1.0.2/search.html | 45 ++++++- v1.0.3/customprocessing/index.html | 63 +++++++-- v1.0.3/documenter/index.html | 53 +++++++- v1.0.3/fileformat/index.html | 49 ++++++- v1.0.3/generated/example/index.html | 193 +++++++++++----------------- v1.0.3/index.html | 45 ++++++- v1.0.3/outputformats/index.html | 53 +++++++- v1.0.3/pipeline/index.html | 51 +++++++- v1.0.3/search/index.html | 45 ++++++- v1.0.4/customprocessing/index.html | 63 +++++++-- v1.0.4/documenter/index.html | 53 +++++++- v1.0.4/fileformat/index.html | 49 ++++++- v1.0.4/generated/example/index.html | 193 +++++++++++----------------- v1.0.4/index.html | 45 ++++++- v1.0.4/outputformats/index.html | 53 +++++++- v1.0.4/pipeline/index.html | 51 +++++++- v1.0.4/search/index.html | 45 ++++++- v1.0.5/customprocessing/index.html | 63 +++++++-- v1.0.5/documenter/index.html | 53 +++++++- v1.0.5/fileformat/index.html | 49 ++++++- v1.0.5/generated/example/index.html | 193 +++++++++++----------------- v1.0.5/index.html | 45 ++++++- v1.0.5/outputformats/index.html | 53 +++++++- v1.0.5/pipeline/index.html | 51 +++++++- v1.0.5/search/index.html | 45 ++++++- v1.1.0/customprocessing/index.html | 63 +++++++-- v1.1.0/documenter/index.html | 53 +++++++- v1.1.0/fileformat/index.html | 49 ++++++- v1.1.0/generated/example/index.html | 188 +++++++++++---------------- v1.1.0/index.html | 45 ++++++- v1.1.0/outputformats/index.html | 53 +++++++- v1.1.0/pipeline/index.html | 51 +++++++- v1.1.0/search/index.html | 45 ++++++- v2.0.0/customprocessing/index.html | 63 +++++++-- v2.0.0/documenter/index.html | 53 +++++++- v2.0.0/fileformat/index.html | 49 ++++++- v2.0.0/generated/example/index.html | 188 +++++++++++---------------- v2.0.0/generated/name/index.html | 45 ++++++- v2.0.0/index.html | 45 ++++++- v2.0.0/outputformats/index.html | 53 +++++++- v2.0.0/pipeline/index.html | 51 +++++++- v2.0.0/search/index.html | 45 ++++++- v2.0.2/customprocessing/index.html | 63 +++++++-- v2.0.2/documenter/index.html | 53 +++++++- v2.0.2/fileformat/index.html | 49 ++++++- v2.0.2/generated/example/index.html | 188 +++++++++++---------------- v2.0.2/generated/name/index.html | 45 ++++++- v2.0.2/index.html | 45 ++++++- v2.0.2/outputformats/index.html | 53 +++++++- v2.0.2/pipeline/index.html | 51 +++++++- v2.0.2/search/index.html | 45 ++++++- v2.0.3/customprocessing/index.html | 63 +++++++-- v2.0.3/documenter/index.html | 53 +++++++- v2.0.3/fileformat/index.html | 49 ++++++- v2.0.3/generated/example/index.html | 188 +++++++++++---------------- v2.0.3/generated/name/index.html | 45 ++++++- v2.0.3/index.html | 45 ++++++- v2.0.3/outputformats/index.html | 53 +++++++- v2.0.3/pipeline/index.html | 51 +++++++- v2.0.3/search/index.html | 45 ++++++- v2.0.4/customprocessing/index.html | 63 +++++++-- v2.0.4/documenter/index.html | 53 +++++++- v2.0.4/fileformat/index.html | 49 ++++++- v2.0.4/generated/example/index.html | 188 +++++++++++---------------- v2.0.4/generated/name/index.html | 45 ++++++- v2.0.4/index.html | 45 ++++++- v2.0.4/outputformats/index.html | 53 +++++++- v2.0.4/pipeline/index.html | 51 +++++++- v2.0.4/search/index.html | 45 ++++++- v2.1.0/customprocessing.html | 63 +++++++-- v2.1.0/documenter.html | 51 +++++++- v2.1.0/fileformat.html | 49 ++++++- v2.1.0/generated/example.html | 188 +++++++++++---------------- v2.1.0/generated/name.html | 45 ++++++- v2.1.0/index.html | 45 ++++++- v2.1.0/outputformats.html | 51 +++++++- v2.1.0/pipeline.html | 51 +++++++- v2.1.0/search.html | 45 ++++++- v2.1.1/customprocessing/index.html | 63 +++++++-- v2.1.1/documenter/index.html | 51 +++++++- v2.1.1/fileformat/index.html | 49 ++++++- v2.1.1/generated/example/index.html | 188 +++++++++++---------------- v2.1.1/generated/name/index.html | 45 ++++++- v2.1.1/index.html | 45 ++++++- v2.1.1/outputformats/index.html | 51 +++++++- v2.1.1/pipeline/index.html | 51 +++++++- v2.1.1/search/index.html | 45 ++++++- v2.2.0/customprocessing/index.html | 63 +++++++-- v2.2.0/documenter/index.html | 53 +++++++- v2.2.0/fileformat/index.html | 49 ++++++- v2.2.0/generated/example/index.html | 188 +++++++++++---------------- v2.2.0/generated/name/index.html | 45 ++++++- v2.2.0/index.html | 45 ++++++- v2.2.0/outputformats/index.html | 51 +++++++- v2.2.0/pipeline/index.html | 51 +++++++- v2.2.0/search/index.html | 45 ++++++- v2.2.1/customprocessing/index.html | 63 +++++++-- v2.2.1/documenter/index.html | 53 +++++++- v2.2.1/fileformat/index.html | 49 ++++++- v2.2.1/generated/example/index.html | 188 +++++++++++---------------- v2.2.1/generated/name/index.html | 45 ++++++- v2.2.1/index.html | 45 ++++++- v2.2.1/outputformats/index.html | 51 +++++++- v2.2.1/pipeline/index.html | 51 +++++++- v2.2.1/search/index.html | 45 ++++++- v2.3.0/customprocessing/index.html | 63 +++++++-- v2.3.0/documenter/index.html | 53 +++++++- v2.3.0/fileformat/index.html | 49 ++++++- v2.3.0/generated/example/index.html | 188 +++++++++++---------------- v2.3.0/generated/name/index.html | 45 ++++++- v2.3.0/index.html | 45 ++++++- v2.3.0/outputformats/index.html | 51 +++++++- v2.3.0/pipeline/index.html | 51 +++++++- v2.3.0/search/index.html | 45 ++++++- v2.3.1/customprocessing/index.html | 63 +++++++-- v2.3.1/documenter/index.html | 53 +++++++- v2.3.1/fileformat/index.html | 49 ++++++- v2.3.1/generated/example/index.html | 192 +++++++++++---------------- v2.3.1/generated/name/index.html | 45 ++++++- v2.3.1/index.html | 45 ++++++- v2.3.1/outputformats/index.html | 51 +++++++- v2.3.1/pipeline/index.html | 51 +++++++- v2.3.1/search/index.html | 45 ++++++- v2.3.1/tips/index.html | 47 ++++++- v2.4.0/customprocessing/index.html | 63 +++++++-- v2.4.0/documenter/index.html | 53 +++++++- v2.4.0/fileformat/index.html | 49 ++++++- v2.4.0/generated/example/index.html | 159 +++++++++++------------ v2.4.0/generated/name/index.html | 45 ++++++- v2.4.0/index.html | 45 ++++++- v2.4.0/outputformats/index.html | 59 +++++++-- v2.4.0/pipeline/index.html | 51 +++++++- v2.4.0/search/index.html | 45 ++++++- v2.4.0/tips/index.html | 47 ++++++- v2.5.0/customprocessing/index.html | 63 +++++++-- v2.5.0/documenter/index.html | 53 +++++++- v2.5.0/fileformat/index.html | 49 ++++++- v2.5.0/generated/example/index.html | 159 +++++++++++------------ v2.5.0/generated/name/index.html | 45 ++++++- v2.5.0/index.html | 45 ++++++- v2.5.0/outputformats/index.html | 59 +++++++-- v2.5.0/pipeline/index.html | 51 +++++++- v2.5.0/search/index.html | 45 ++++++- v2.5.0/tips/index.html | 47 ++++++- v2.5.1/customprocessing/index.html | 63 +++++++-- v2.5.1/documenter/index.html | 53 +++++++- v2.5.1/fileformat/index.html | 49 ++++++- v2.5.1/generated/example/index.html | 159 +++++++++++------------ v2.5.1/generated/name/index.html | 45 ++++++- v2.5.1/index.html | 45 ++++++- v2.5.1/outputformats/index.html | 59 +++++++-- v2.5.1/pipeline/index.html | 51 +++++++- v2.5.1/search/index.html | 45 ++++++- v2.5.1/tips/index.html | 47 ++++++- v2.6.0/customprocessing/index.html | 63 +++++++-- v2.6.0/documenter/index.html | 53 +++++++- v2.6.0/fileformat/index.html | 49 ++++++- v2.6.0/generated/example/index.html | 159 +++++++++++------------ v2.6.0/generated/name/index.html | 45 ++++++- v2.6.0/index.html | 45 ++++++- v2.6.0/outputformats/index.html | 59 +++++++-- v2.6.0/pipeline/index.html | 51 +++++++- v2.6.0/search/index.html | 45 ++++++- v2.6.0/tips/index.html | 47 ++++++- v2.7.0/customprocessing/index.html | 63 +++++++-- v2.7.0/documenter/index.html | 53 +++++++- v2.7.0/fileformat/index.html | 51 +++++++- v2.7.0/generated/example/index.html | 159 +++++++++++------------ v2.7.0/generated/name/index.html | 45 ++++++- v2.7.0/index.html | 45 ++++++- v2.7.0/outputformats/index.html | 59 +++++++-- v2.7.0/pipeline/index.html | 51 +++++++- v2.7.0/search/index.html | 45 ++++++- v2.7.0/tips/index.html | 47 ++++++- v2.8.0/customprocessing/index.html | 63 +++++++-- v2.8.0/documenter/index.html | 53 +++++++- v2.8.0/fileformat/index.html | 51 +++++++- v2.8.0/generated/example/index.html | 159 +++++++++++------------ v2.8.0/generated/name/index.html | 45 ++++++- v2.8.0/index.html | 45 ++++++- v2.8.0/outputformats/index.html | 59 +++++++-- v2.8.0/pipeline/index.html | 51 +++++++- v2.8.0/search/index.html | 45 ++++++- v2.8.0/tips/index.html | 47 ++++++- 247 files changed, 12045 insertions(+), 3710 deletions(-) diff --git a/v0.1.0/customprocessing.html b/v0.1.0/customprocessing.html index ec847b0..d2a7d76 100644 --- a/v0.1.0/customprocessing.html +++ b/v0.1.0/customprocessing.html @@ -1,8 +1,49 @@ - -5. Custom pre- and post-processing · Literate.jl
5. Custom pre- and post-processing

5. Custom pre- and post-processing

Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

#' # Example
-#' This example was generated DATEOFTODAY
+5. Custom pre- and post-processing · Literate.jl
5. Custom pre- and post-processing
5. Custom pre- and post-processing
Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
#' # Example
+#' This example was generated DATEOFTODAY
 
 x = 1 // 3
where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
Literate.markdown("input.jl", "outputdir"; preprocess = update_date)

+end

which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:

Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
\ No newline at end of file diff --git a/v0.1.0/documenter.html b/v0.1.0/documenter.html index c7167fc..e66510a 100644 --- a/v0.1.0/documenter.html +++ b/v0.1.0/documenter.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
6. Interaction with Documenter.jl

6. Interaction with Documenter.jl

Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

Literate.markdown:

Literate.script:

\ No newline at end of file diff --git a/v0.1.0/fileformat.html b/v0.1.0/fileformat.html index 2ea4848..892a61a 100644 --- a/v0.1.0/fileformat.html +++ b/v0.1.0/fileformat.html @@ -1,17 +1,58 @@ - -2. File Format · Literate.jl
2. File Format

2. File Format

The source file format for Literate 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.

2.1. Syntax

The basic syntax is simple:

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:

#' # Rational numbers
-#'
-#' In julia rational numbers can be constructed with the `//` operator.
-#' Lets define two rational numbers, `x` and `y`:
+2. File Format · Literate.jl
2. File Format
2. File Format
The source file format for Literate 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.
2.1. Syntax
The basic syntax is simple:
  • lines starting with #' is 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:
#' # 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 # 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 (for example in the test/runtests.jl script, to include the example in the test suite).
  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
For simple use this is all you need to know. The following additional special syntax can also be used:
There is also some default convenience replacements that will always be performed, see Default Replacements.
2.2. Filtering Lines
It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
  • #md: line exclusive to markdown output,
  • #nb: line exclusive to notebook output,
  • #jl: line exclusive to script output,
  • #src: line exclusive to the source code and thus filtered out unconditionally.
Lines starting with one of these tokens are filtered out in the preprocessing step.
Suppose, for example, that we want to include a docstring within a @docs block 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:
#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 the leading #md from the lines. Beware that the space after the tag is also removed.
The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
using Test                      #src
-@test result == expected_result #src
2.3. Default Replacements
The following convenience "macros" are always expanded:
  • @__NAME__
    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
  • @__REPO__ROOT_URL__
    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
  • @__NBVIEWER_ROOT_URL__
    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

+z = x + y

In the lines #' 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:

For simple use this is all you need to know. The following additional special syntax can also be used:

There is also some default convenience replacements that will always be performed, see Default Replacements.

2.2. Filtering Lines

It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:

Lines starting with one of these tokens are filtered out in the preprocessing step.

Suppose, for example, that we want to include a docstring within a @docs block 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:

#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 the leading #md from the lines. Beware that the space after the tag is also removed.

The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:

using Test                      #src
+@test result == expected_result #src

2.3. Default Replacements

The following convenience "macros" are always expanded:

\ No newline at end of file diff --git a/v0.1.0/generated/example.html b/v0.1.0/generated/example.html index 4f683c4..6141716 100644 --- a/v0.1.0/generated/example.html +++ b/v0.1.0/generated/example.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
7. Example

7. Example

This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

Basic syntax

The basic syntax for Literate is simple, lines starting with #' is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

x = 1//3
-y = 2//5
2//5

In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

x + y
11//15
x * y
2//15

Output Capturing

Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
7. Example
7. Example
This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
Basic syntax
The basic syntax for Literate is simple, lines starting with #' is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
x = 1//3
+y = 2//5
2//5
In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
  • This line starts with #md and is thus only visible in the markdown output.
The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
x + y
11//15
x * y
2//15
Output Capturing
Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,4 +51,4 @@ foo()
This string is printed to std
  1
  2
  3
- 4
Custom processing
It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
z = 1.0 + 2.0im
1.0 + 2.0im
Documenter.jl interaction
In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
This page was generated using Literate.jl.

+ 4

Custom processing

It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

z = 1.0 + 2.0im
1.0 + 2.0im

Documenter.jl interaction

In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

This page was generated using Literate.jl.

\ No newline at end of file diff --git a/v0.1.0/index.html b/v0.1.0/index.html index 1d14697..a39d590 100644 --- a/v0.1.0/index.html +++ b/v0.1.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
1. Introduction

1. Introduction

Welcome to the documentation for Literate – a simplistic package for Literate Programming.

What?

Literate is a package that generate markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

The public interface consists mainly of three functions, which all takes the same script file as input, but generates different output:

Why?

Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

+1. Introduction · Literate.jl
1. Introduction

1. Introduction

Welcome to the documentation for Literate – a simplistic package for Literate Programming.

What?

Literate is a package that generate markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

The public interface consists mainly of three functions, which all takes the same script file as input, but generates different output:

Why?

Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

\ No newline at end of file diff --git a/v0.1.0/outputformats.html b/v0.1.0/outputformats.html index d984f97..ef6f246 100644 --- a/v0.1.0/outputformats.html +++ b/v0.1.0/outputformats.html @@ -1,16 +1,57 @@ - -4. Output Formats · Literate.jl
4. Output Formats

4. Output Formats

When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

#' # Rational numbers
-#'
-#' In julia rational numbers can be constructed with the `//` operator.
-#' Lets define two rational numbers, `x` and `y`:
+4. Output Formats · Literate.jl
4. Output Formats
4. Output Formats
When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
#' # 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
and see how this is rendered in each of the output formats.
4.1. Markdown Output
The (default) markdown output of the source snippet above is as follows
# Rational numbers
+z = x + y
and see how this is rendered in each of the output formats.
4.1. Markdown Output
The (default) markdown output of the source snippet above is as follows
# Rational numbers
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
@@ -27,7 +68,7 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
We note that lines starting with #' is printed as regular markdown, and the code lines have been wrapped in @example blocks.
Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)
Generate a markdown file from inputfile and write the result to the directoryoutputdir.
Keyword arguments:
  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
  • codefence: A Pair of opening and closing code fence. Defaults to
    "```@example $(name)" => "```"
    if documenter = true and
    "```julia" => "```"
    if documenter = false.
source
4.2. Notebook Output
The (default) notebook output of the source snippet above is as follows
        │ # Rational numbers
+```
We note that lines starting with #' is printed as regular markdown, and the code lines have been wrapped in @example blocks.
Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)
Generate a markdown file from inputfile and write the result to the directoryoutputdir.
Keyword arguments:
  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
  • codefence: A Pair of opening and closing code fence. Defaults to
    "```@example $(name)" => "```"
    if documenter = true and
    "```julia" => "```"
    if documenter = false.
source
4.2. Notebook Output
The (default) notebook output of the source snippet above is as follows
        │ # Rational numbers
         │
         │ In julia rational numbers can be constructed with the `//` operator.
         │ Lets define two rational numbers, `x` and `y`:
@@ -41,8 +82,8 @@ Out[2]: │ 2//5
         │ When adding `x` and `y` together we obtain a new rational number:
 
 In[3]:  │ z = x + y
-Out[3]: │ 11/15
We note that lines starting with #' is put in markdown cells, and the code lines have been put in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)
Generate a notebook from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
source
4.3. Script Output
The (default) script output of the source snippet above is as follows
x = 1//3
+Out[3]: │ 11/15
We note that lines starting with #' is put in markdown cells, and the code lines have been put in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)
Generate a notebook from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
source
4.3. Script Output
The (default) script output of the source snippet above is as follows
x = 1//3
 
 y = 2//5
 
-z = x + y
We note that lines starting with #' are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)
Generate a plain script file from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
  • keep_comments: boolean that, if set to true, keeps markdown lines (#') as comments in the output script. Defaults to false.
source

+z = x + y

We note that lines starting with #' are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)

Generate a plain script file from inputfile and write the result to outputdir.

Keyword arguments:

  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.

  • keep_comments: boolean that, if set to true, keeps markdown lines (#') as comments in the output script. Defaults to false.

source
\ No newline at end of file diff --git a/v0.1.0/pipeline.html b/v0.1.0/pipeline.html index 6d11149..5bb9378 100644 --- a/v0.1.0/pipeline.html +++ b/v0.1.0/pipeline.html @@ -1,29 +1,70 @@ - -3. Processing pipeline · Literate.jl
3. Processing pipeline

3. Processing pipeline

The generation of output follows the same pipeline for all output formats:

  1. Pre-processing

  2. Parsing

  3. Document generation

  4. Post-processing

  5. Writing to file

3.1. Pre-processing

The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

3.2. Parsing

After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
+3. Processing pipeline · Literate.jl
3. Processing pipeline
3. Processing pipeline
The generation of output follows the same pipeline for all output formats:
  1. Pre-processing
  2. Parsing
  3. Document generation
  4. Post-processing
  5. Writing to file
3.1. Pre-processing
The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
3.2. Parsing
After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
+#' 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`:                         ┘
+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
+#' 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 #' tokens are also removed from the markdown chunks. Finally we would end up with the following 4 chunks:
Chunks #1:
# Rational numbers
+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 #' tokens are also removed from the markdown chunks. Finally we would end up with the following 4 chunks:
Chunks #1:
# Rational numbers
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
Chunk #2:
x = 1 // 3
-y = 2 // 5
Chunk #3:
When adding `x` and `y` together we obtain a new rational number:
Chunk #4:
z = x + y
It is then up to the Document generation step to decide how these chunks should be treated.
Custom control over chunk splits
Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
x = 1 // 3
+y = 2 // 5
Chunk #3:
When adding `x` and `y` together we obtain a new rational number:
Chunk #4:
z = x + y
It is then up to the Document generation step to decide how these chunks should be treated.
Custom control over chunk splits
Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
The example above would result in two consecutive code-chunks.
Tip
The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
3.3. Document generation
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, Notebook Output and Script Output. In short, the following is happening:
  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
  • Script output: markdown chunks are discarded, code chunks are printed as-is.
3.4. Post-processing
When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
3.5. Writing to file
The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

+z = x + y

The example above would result in two consecutive code-chunks.

Tip

The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

3.3. Document generation

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, Notebook Output and Script Output. In short, the following is happening:

3.4. Post-processing

When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

3.5. Writing to file

The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

\ No newline at end of file diff --git a/v0.1.0/search.html b/v0.1.0/search.html index 674f80b..e549140 100644 --- a/v0.1.0/search.html +++ b/v0.1.0/search.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
Search

Search

Number of results: loading...

+Search · Literate.jl
Search

Search

Number of results: loading...

\ No newline at end of file diff --git a/v0.2.0/customprocessing.html b/v0.2.0/customprocessing.html index 96726fb..b03b48f 100644 --- a/v0.2.0/customprocessing.html +++ b/v0.2.0/customprocessing.html @@ -1,8 +1,49 @@ - -5. Custom pre- and post-processing · Literate.jl
5. Custom pre- and post-processing

5. Custom pre- and post-processing

Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

# # Example
+5. Custom pre- and post-processing · Literate.jl
5. Custom pre- and post-processing
5. Custom pre- and post-processing
Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
# # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
Literate.markdown("input.jl", "outputdir"; preprocess = update_date)

+end

which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:

Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
\ No newline at end of file diff --git a/v0.2.0/documenter.html b/v0.2.0/documenter.html index c7167fc..e66510a 100644 --- a/v0.2.0/documenter.html +++ b/v0.2.0/documenter.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
6. Interaction with Documenter.jl

6. Interaction with Documenter.jl

Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

Literate.markdown:

Literate.script:

\ No newline at end of file diff --git a/v0.2.0/fileformat.html b/v0.2.0/fileformat.html index c1e5b83..9b54a1e 100644 --- a/v0.2.0/fileformat.html +++ b/v0.2.0/fileformat.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
2. File Format

2. File Format

The source file format for Literate 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.

2.1. Syntax

The basic syntax is simple:

Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

Lets look at a simple example:

# # Rational numbers
+2. File Format · Literate.jl
2. File Format
2. File Format
The source file format for Literate 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.
2.1. Syntax
The basic syntax is simple:
  • lines starting with # are treated as markdown,
  • all other lines are treated as julia code.
Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
Lets look at a simple example:
# # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
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 (for example in the test/runtests.jl script, to include the example in the test suite).
  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
For simple use this is all you need to know. The following additional special syntax can also be used:
There is also some default convenience replacements that will always be performed, see Default Replacements.
2.2. Filtering Lines
It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
  • #md: line exclusive to markdown output,
  • #nb: line exclusive to notebook output,
  • #jl: line exclusive to script output,
  • #src: line exclusive to the source code and thus filtered out unconditionally.
Lines starting with one of these tokens are filtered out in the preprocessing step.
Suppose, for example, that we want to include a docstring within a @docs block 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:
#md # ```@docs
+z = x + y
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 (for example in the test/runtests.jl script, to include the example in the test suite).
  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
For simple use this is all you need to know. The following additional special syntax can also be used:
There is also some default convenience replacements that will always be performed, see Default Replacements.
2.2. Filtering Lines
It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
  • #md: line exclusive to markdown output,
  • #nb: line exclusive to notebook output,
  • #jl: line exclusive to script output,
  • #src: line exclusive to the source code and thus filtered out unconditionally.
Lines starting with one of these tokens are filtered out in the preprocessing step.
Suppose, for example, that we want to include a docstring within a @docs block 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:
#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 the leading #md from the lines. Beware that the space after the tag is also removed.
The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
using Test                      #src
-@test result == expected_result #src
2.3. Default Replacements
The following convenience "macros" are always expanded:
  • @__NAME__
    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
  • @__REPO__ROOT_URL__
    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
  • @__NBVIEWER_ROOT_URL__
    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

+@test result == expected_result #src

2.3. Default Replacements

The following convenience "macros" are always expanded:

\ No newline at end of file diff --git a/v0.2.0/generated/example.html b/v0.2.0/generated/example.html index 1882c89..18f15a9 100644 --- a/v0.2.0/generated/example.html +++ b/v0.2.0/generated/example.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
7. Example

7. Example

This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

Basic syntax

The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

x = 1//3
-y = 2//5
2//5

In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

x + y
11//15
x * y
2//15

Output Capturing

Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
7. Example
7. Example
This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
Basic syntax
The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
x = 1//3
+y = 2//5
2//5
In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
  • This line starts with #md and is thus only visible in the markdown output.
The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
x + y
11//15
x * y
2//15
Output Capturing
Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,4 +51,4 @@ foo()
This string is printed to std
  1
  2
  3
- 4
Custom processing
It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
z = 1.0 + 2.0im
1.0 + 2.0im
Documenter.jl interaction
In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
This page was generated using Literate.jl.

+ 4

Custom processing

It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

z = 1.0 + 2.0im
1.0 + 2.0im

Documenter.jl interaction

In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

This page was generated using Literate.jl.

\ No newline at end of file diff --git a/v0.2.0/index.html b/v0.2.0/index.html index f96bb9a..03d8df7 100644 --- a/v0.2.0/index.html +++ b/v0.2.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
1. Introduction

1. Introduction

Welcome to the documentation for Literate – a simplistic package for Literate Programming.

What?

Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

Why?

Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

+1. Introduction · Literate.jl
1. Introduction

1. Introduction

Welcome to the documentation for Literate – a simplistic package for Literate Programming.

What?

Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

Why?

Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

\ No newline at end of file diff --git a/v0.2.0/outputformats.html b/v0.2.0/outputformats.html index 65e02a5..16506e8 100644 --- a/v0.2.0/outputformats.html +++ b/v0.2.0/outputformats.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
4. Output Formats

4. Output Formats

When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

# # Rational numbers
+4. Output Formats · Literate.jl
4. Output Formats
4. Output Formats
When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
# # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
and see how this is rendered in each of the output formats.
4.1. Markdown Output
The (default) markdown output of the source snippet above is as follows
```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
and see how this is rendered in each of the output formats.
4.1. Markdown Output
The (default) markdown output of the source snippet above is as follows
```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)
Generate a markdown file from inputfile and write the result to the directoryoutputdir.
Keyword arguments:
  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
  • codefence: A Pair of opening and closing code fence. Defaults to
    "```@example $(name)" => "```"
    if documenter = true and
    "```julia" => "```"
    if documenter = false.
source
4.2. Notebook Output
The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)
Generate a notebook from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
source
4.3. Script Output
The (default) script output of the source snippet above is as follows
x = 1//3
+```
We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)
Generate a markdown file from inputfile and write the result to the directoryoutputdir.
Keyword arguments:
  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
  • codefence: A Pair of opening and closing code fence. Defaults to
    "```@example $(name)" => "```"
    if documenter = true and
    "```julia" => "```"
    if documenter = false.
source
4.2. Notebook Output
The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)
Generate a notebook from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
source
4.3. Script Output
The (default) script output of the source snippet above is as follows
x = 1//3
 
 y = 2//5
 
-z = x + y
We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)
Generate a plain script file from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
source

+z = x + y

We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)

Generate a plain script file from inputfile and write the result to outputdir.

Keyword arguments:

  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.

  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.

source
\ No newline at end of file diff --git a/v0.2.0/pipeline.html b/v0.2.0/pipeline.html index 071a080..5d994fd 100644 --- a/v0.2.0/pipeline.html +++ b/v0.2.0/pipeline.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
3. Processing pipeline

3. Processing pipeline

The generation of output follows the same pipeline for all output formats:

  1. Pre-processing

  2. Parsing

  3. Document generation

  4. Post-processing

  5. Writing to file

3.1. Pre-processing

The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

3.2. Parsing

After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

# # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
3. Processing pipeline
3. Processing pipeline
The generation of output follows the same pipeline for all output formats:
  1. Pre-processing
  2. Parsing
  3. Document generation
  4. Post-processing
  5. Writing to file
3.1. Pre-processing
The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
3.2. Parsing
After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
Chunk #2:
x = 1 // 3
-y = 2 // 5
Chunk #3:
When adding `x` and `y` together we obtain a new rational number:
Chunk #4:
z = x + y
It is then up to the Document generation step to decide how these chunks should be treated.
Custom control over chunk splits
Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
x = 1 // 3
+y = 2 // 5
Chunk #3:
When adding `x` and `y` together we obtain a new rational number:
Chunk #4:
z = x + y
It is then up to the Document generation step to decide how these chunks should be treated.
Custom control over chunk splits
Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
The example above would result in two consecutive code-chunks.
Tip
The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
3.3. Document generation
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, Notebook Output and Script Output. Using the default settings, the following is happening:
  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
  • Script output: markdown chunks are discarded, code chunks are printed as-is.
3.4. Post-processing
When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
3.5. Writing to file
The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

+z = x + y

The example above would result in two consecutive code-chunks.

Tip

The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

3.3. Document generation

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, Notebook Output and Script Output. Using the default settings, the following is happening:

3.4. Post-processing

When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

3.5. Writing to file

The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

\ No newline at end of file diff --git a/v0.2.0/search.html b/v0.2.0/search.html index 674f80b..e549140 100644 --- a/v0.2.0/search.html +++ b/v0.2.0/search.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
Search

Search

Number of results: loading...

+Search · Literate.jl
Search

Search

Number of results: loading...

\ No newline at end of file diff --git a/v0.2.1/customprocessing.html b/v0.2.1/customprocessing.html index 96726fb..b03b48f 100644 --- a/v0.2.1/customprocessing.html +++ b/v0.2.1/customprocessing.html @@ -1,8 +1,49 @@ - -5. Custom pre- and post-processing · Literate.jl
5. Custom pre- and post-processing

5. Custom pre- and post-processing

Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

# # Example
+5. Custom pre- and post-processing · Literate.jl
5. Custom pre- and post-processing
5. Custom pre- and post-processing
Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
# # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
Literate.markdown("input.jl", "outputdir"; preprocess = update_date)

+end

which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:

Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
\ No newline at end of file diff --git a/v0.2.1/documenter.html b/v0.2.1/documenter.html index c7167fc..e66510a 100644 --- a/v0.2.1/documenter.html +++ b/v0.2.1/documenter.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
6. Interaction with Documenter.jl

6. Interaction with Documenter.jl

Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

Literate.markdown:

Literate.script:

\ No newline at end of file diff --git a/v0.2.1/fileformat.html b/v0.2.1/fileformat.html index c1e5b83..9b54a1e 100644 --- a/v0.2.1/fileformat.html +++ b/v0.2.1/fileformat.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
2. File Format

2. File Format

The source file format for Literate 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.

2.1. Syntax

The basic syntax is simple:

Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

Lets look at a simple example:

# # Rational numbers
+2. File Format · Literate.jl
2. File Format
2. File Format
The source file format for Literate 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.
2.1. Syntax
The basic syntax is simple:
  • lines starting with # are treated as markdown,
  • all other lines are treated as julia code.
Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
Lets look at a simple example:
# # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
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 (for example in the test/runtests.jl script, to include the example in the test suite).
  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
For simple use this is all you need to know. The following additional special syntax can also be used:
There is also some default convenience replacements that will always be performed, see Default Replacements.
2.2. Filtering Lines
It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
  • #md: line exclusive to markdown output,
  • #nb: line exclusive to notebook output,
  • #jl: line exclusive to script output,
  • #src: line exclusive to the source code and thus filtered out unconditionally.
Lines starting with one of these tokens are filtered out in the preprocessing step.
Suppose, for example, that we want to include a docstring within a @docs block 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:
#md # ```@docs
+z = x + y
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 (for example in the test/runtests.jl script, to include the example in the test suite).
  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
For simple use this is all you need to know. The following additional special syntax can also be used:
There is also some default convenience replacements that will always be performed, see Default Replacements.
2.2. Filtering Lines
It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
  • #md: line exclusive to markdown output,
  • #nb: line exclusive to notebook output,
  • #jl: line exclusive to script output,
  • #src: line exclusive to the source code and thus filtered out unconditionally.
Lines starting with one of these tokens are filtered out in the preprocessing step.
Suppose, for example, that we want to include a docstring within a @docs block 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:
#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 the leading #md from the lines. Beware that the space after the tag is also removed.
The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
using Test                      #src
-@test result == expected_result #src
2.3. Default Replacements
The following convenience "macros" are always expanded:
  • @__NAME__
    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
  • @__REPO__ROOT_URL__
    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
  • @__NBVIEWER_ROOT_URL__
    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

+@test result == expected_result #src

2.3. Default Replacements

The following convenience "macros" are always expanded:

\ No newline at end of file diff --git a/v0.2.1/generated/example.html b/v0.2.1/generated/example.html index e62813c..98179cc 100644 --- a/v0.2.1/generated/example.html +++ b/v0.2.1/generated/example.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
7. Example

7. Example

This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

Basic syntax

The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

x = 1//3
-y = 2//5
2//5

In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

x + y
11//15
x * y
2//15

Output Capturing

Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
7. Example
7. Example
This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
Basic syntax
The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
x = 1//3
+y = 2//5
2//5
In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
  • This line starts with #md and is thus only visible in the markdown output.
The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
x + y
11//15
x * y
2//15
Output Capturing
Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,4 +51,4 @@ foo()
This string is printed to std
  1
  2
  3
- 4
Custom processing
It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
z = 1.0 + 2.0im
1.0 + 2.0im
Documenter.jl interaction
In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
This page was generated using Literate.jl.

+ 4

Custom processing

It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

z = 1.0 + 2.0im
1.0 + 2.0im

Documenter.jl interaction

In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

This page was generated using Literate.jl.

\ No newline at end of file diff --git a/v0.2.1/index.html b/v0.2.1/index.html index f96bb9a..03d8df7 100644 --- a/v0.2.1/index.html +++ b/v0.2.1/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
1. Introduction

1. Introduction

Welcome to the documentation for Literate – a simplistic package for Literate Programming.

What?

Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

Why?

Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

+1. Introduction · Literate.jl
1. Introduction

1. Introduction

Welcome to the documentation for Literate – a simplistic package for Literate Programming.

What?

Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

Why?

Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

\ No newline at end of file diff --git a/v0.2.1/outputformats.html b/v0.2.1/outputformats.html index 4f8174f..a738cb8 100644 --- a/v0.2.1/outputformats.html +++ b/v0.2.1/outputformats.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
4. Output Formats

4. Output Formats

When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

# # Rational numbers
+4. Output Formats · Literate.jl
4. Output Formats
4. Output Formats
When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
# # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
and see how this is rendered in each of the output formats.
4.1. Markdown Output
The (default) markdown output of the source snippet above is as follows
```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
and see how this is rendered in each of the output formats.
4.1. Markdown Output
The (default) markdown output of the source snippet above is as follows
```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)
Generate a markdown file from inputfile and write the result to the directoryoutputdir.
Keyword arguments:
  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
  • codefence: A Pair of opening and closing code fence. Defaults to
    "```@example $(name)" => "```"
    if documenter = true and
    "```julia" => "```"
    if documenter = false.
source
4.2. Notebook Output
The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)
Generate a notebook from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
source
4.3. Script Output
The (default) script output of the source snippet above is as follows
x = 1//3
+```
We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)
Generate a markdown file from inputfile and write the result to the directoryoutputdir.
Keyword arguments:
  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
  • codefence: A Pair of opening and closing code fence. Defaults to
    "```@example $(name)" => "```"
    if documenter = true and
    "```julia" => "```"
    if documenter = false.
source
4.2. Notebook Output
The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)
Generate a notebook from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
source
4.3. Script Output
The (default) script output of the source snippet above is as follows
x = 1//3
 
 y = 2//5
 
-z = x + y
We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)
Generate a plain script file from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
source

+z = x + y

We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)

Generate a plain script file from inputfile and write the result to outputdir.

Keyword arguments:

  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.

  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.

source
\ No newline at end of file diff --git a/v0.2.1/pipeline.html b/v0.2.1/pipeline.html index 071a080..5d994fd 100644 --- a/v0.2.1/pipeline.html +++ b/v0.2.1/pipeline.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
3. Processing pipeline

3. Processing pipeline

The generation of output follows the same pipeline for all output formats:

  1. Pre-processing

  2. Parsing

  3. Document generation

  4. Post-processing

  5. Writing to file

3.1. Pre-processing

The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

3.2. Parsing

After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

# # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
3. Processing pipeline
3. Processing pipeline
The generation of output follows the same pipeline for all output formats:
  1. Pre-processing
  2. Parsing
  3. Document generation
  4. Post-processing
  5. Writing to file
3.1. Pre-processing
The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
3.2. Parsing
After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
Chunk #2:
x = 1 // 3
-y = 2 // 5
Chunk #3:
When adding `x` and `y` together we obtain a new rational number:
Chunk #4:
z = x + y
It is then up to the Document generation step to decide how these chunks should be treated.
Custom control over chunk splits
Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
x = 1 // 3
+y = 2 // 5
Chunk #3:
When adding `x` and `y` together we obtain a new rational number:
Chunk #4:
z = x + y
It is then up to the Document generation step to decide how these chunks should be treated.
Custom control over chunk splits
Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
The example above would result in two consecutive code-chunks.
Tip
The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
3.3. Document generation
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, Notebook Output and Script Output. Using the default settings, the following is happening:
  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
  • Script output: markdown chunks are discarded, code chunks are printed as-is.
3.4. Post-processing
When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
3.5. Writing to file
The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

+z = x + y

The example above would result in two consecutive code-chunks.

Tip

The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

3.3. Document generation

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, Notebook Output and Script Output. Using the default settings, the following is happening:

3.4. Post-processing

When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

3.5. Writing to file

The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

\ No newline at end of file diff --git a/v0.2.1/search.html b/v0.2.1/search.html index 674f80b..e549140 100644 --- a/v0.2.1/search.html +++ b/v0.2.1/search.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
Search

Search

Number of results: loading...

+Search · Literate.jl
Search

Search

Number of results: loading...

\ No newline at end of file diff --git a/v0.2.2/customprocessing.html b/v0.2.2/customprocessing.html index 96726fb..b03b48f 100644 --- a/v0.2.2/customprocessing.html +++ b/v0.2.2/customprocessing.html @@ -1,8 +1,49 @@ - -5. Custom pre- and post-processing · Literate.jl
5. Custom pre- and post-processing

5. Custom pre- and post-processing

Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

# # Example
+5. Custom pre- and post-processing · Literate.jl
5. Custom pre- and post-processing
5. Custom pre- and post-processing
Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
# # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
Literate.markdown("input.jl", "outputdir"; preprocess = update_date)

+end

which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:

Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
\ No newline at end of file diff --git a/v0.2.2/documenter.html b/v0.2.2/documenter.html index c7167fc..e66510a 100644 --- a/v0.2.2/documenter.html +++ b/v0.2.2/documenter.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
6. Interaction with Documenter.jl

6. Interaction with Documenter.jl

Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

Literate.markdown:

Literate.script:

\ No newline at end of file diff --git a/v0.2.2/fileformat.html b/v0.2.2/fileformat.html index c1e5b83..9b54a1e 100644 --- a/v0.2.2/fileformat.html +++ b/v0.2.2/fileformat.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
2. File Format

2. File Format

The source file format for Literate 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.

2.1. Syntax

The basic syntax is simple:

Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

Lets look at a simple example:

# # Rational numbers
+2. File Format · Literate.jl
2. File Format
2. File Format
The source file format for Literate 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.
2.1. Syntax
The basic syntax is simple:
  • lines starting with # are treated as markdown,
  • all other lines are treated as julia code.
Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
Lets look at a simple example:
# # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
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 (for example in the test/runtests.jl script, to include the example in the test suite).
  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
For simple use this is all you need to know. The following additional special syntax can also be used:
There is also some default convenience replacements that will always be performed, see Default Replacements.
2.2. Filtering Lines
It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
  • #md: line exclusive to markdown output,
  • #nb: line exclusive to notebook output,
  • #jl: line exclusive to script output,
  • #src: line exclusive to the source code and thus filtered out unconditionally.
Lines starting with one of these tokens are filtered out in the preprocessing step.
Suppose, for example, that we want to include a docstring within a @docs block 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:
#md # ```@docs
+z = x + y
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 (for example in the test/runtests.jl script, to include the example in the test suite).
  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
For simple use this is all you need to know. The following additional special syntax can also be used:
There is also some default convenience replacements that will always be performed, see Default Replacements.
2.2. Filtering Lines
It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
  • #md: line exclusive to markdown output,
  • #nb: line exclusive to notebook output,
  • #jl: line exclusive to script output,
  • #src: line exclusive to the source code and thus filtered out unconditionally.
Lines starting with one of these tokens are filtered out in the preprocessing step.
Suppose, for example, that we want to include a docstring within a @docs block 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:
#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 the leading #md from the lines. Beware that the space after the tag is also removed.
The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
using Test                      #src
-@test result == expected_result #src
2.3. Default Replacements
The following convenience "macros" are always expanded:
  • @__NAME__
    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
  • @__REPO__ROOT_URL__
    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
  • @__NBVIEWER_ROOT_URL__
    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

+@test result == expected_result #src

2.3. Default Replacements

The following convenience "macros" are always expanded:

\ No newline at end of file diff --git a/v0.2.2/generated/example.html b/v0.2.2/generated/example.html index c899e2f..5a0a908 100644 --- a/v0.2.2/generated/example.html +++ b/v0.2.2/generated/example.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
7. Example

7. Example

This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

Basic syntax

The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

x = 1//3
-y = 2//5
2//5

In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

x + y
11//15
x * y
2//15

Output Capturing

Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
7. Example
7. Example
This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
Basic syntax
The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
x = 1//3
+y = 2//5
2//5
In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
  • This line starts with #md and is thus only visible in the markdown output.
The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
x + y
11//15
x * y
2//15
Output Capturing
Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,121 +51,55 @@ foo()
This string is printed to std
  1
  2
  3
- 4
Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
using Plots
+ 4
Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
using Plots
 x = linspace(0, 6π, 1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])

-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   554.571,259.674 555.097,256.559 555.622,253.423 556.148,250.268 556.674,247.094 557.2,243.902 557.725,240.694 558.251,237.471 558.777,234.234 559.302,230.984 
   559.828,227.723 560.354,224.45 560.88,221.169 561.405,217.879 561.931,214.582 562.457,211.279 562.982,207.972 563.508,204.661 564.034,201.347 564.56,198.032 
   
-  "/>
-
   554.571,33.5209 555.097,32.3871 555.622,31.3124 556.148,30.297 556.674,29.3413 557.2,28.4457 557.725,27.6104 558.251,26.8359 558.777,26.1222 559.302,25.4698 
   559.828,24.8788 560.354,24.3495 560.88,23.8819 561.405,23.4764 561.931,23.133 562.457,22.8519 562.982,22.6332 563.508,22.4769 564.034,22.3831 564.56,22.3518 
   
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
Custom processing
It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
z = 1.0 + 2.0im
1.0 + 2.0im
Documenter.jl interaction
In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
This page was generated using Literate.jl.

+  " style="stroke:#e26f46; stroke-width:1; stroke-opacity:1; fill:none">y2

Custom processing

It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

z = 1.0 + 2.0im
1.0 + 2.0im

Documenter.jl interaction

In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

This page was generated using Literate.jl.

\ No newline at end of file diff --git a/v0.2.2/index.html b/v0.2.2/index.html index f96bb9a..03d8df7 100644 --- a/v0.2.2/index.html +++ b/v0.2.2/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
1. Introduction

1. Introduction

Welcome to the documentation for Literate – a simplistic package for Literate Programming.

What?

Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

Why?

Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

+1. Introduction · Literate.jl
1. Introduction

1. Introduction

Welcome to the documentation for Literate – a simplistic package for Literate Programming.

What?

Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

Why?

Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

\ No newline at end of file diff --git a/v0.2.2/outputformats.html b/v0.2.2/outputformats.html index 5401af2..11983b8 100644 --- a/v0.2.2/outputformats.html +++ b/v0.2.2/outputformats.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
4. Output Formats

4. Output Formats

When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

# # Rational numbers
+4. Output Formats · Literate.jl
4. Output Formats
4. Output Formats
When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
# # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
and see how this is rendered in each of the output formats.
4.1. Markdown Output
The (default) markdown output of the source snippet above is as follows
```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
and see how this is rendered in each of the output formats.
4.1. Markdown Output
The (default) markdown output of the source snippet above is as follows
```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)
Generate a markdown file from inputfile and write the result to the directoryoutputdir.
Keyword arguments:
  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
  • codefence: A Pair of opening and closing code fence. Defaults to
    "```@example $(name)" => "```"
    if documenter = true and
    "```julia" => "```"
    if documenter = false.
source
4.2. Notebook Output
The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)
Generate a notebook from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
source
4.3. Script Output
The (default) script output of the source snippet above is as follows
x = 1//3
+```
We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)
Generate a markdown file from inputfile and write the result to the directoryoutputdir.
Keyword arguments:
  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
  • codefence: A Pair of opening and closing code fence. Defaults to
    "```@example $(name)" => "```"
    if documenter = true and
    "```julia" => "```"
    if documenter = false.
source
4.2. Notebook Output
The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)
Generate a notebook from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
source
4.3. Script Output
The (default) script output of the source snippet above is as follows
x = 1//3
 
 y = 2//5
 
-z = x + y
We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)
Generate a plain script file from inputfile and write the result to outputdir.
Keyword arguments:
  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
source

+z = x + y

We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)

Generate a plain script file from inputfile and write the result to outputdir.

Keyword arguments:

  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.

  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.

source
\ No newline at end of file diff --git a/v0.2.2/pipeline.html b/v0.2.2/pipeline.html index 071a080..5d994fd 100644 --- a/v0.2.2/pipeline.html +++ b/v0.2.2/pipeline.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
3. Processing pipeline

3. Processing pipeline

The generation of output follows the same pipeline for all output formats:

  1. Pre-processing

  2. Parsing

  3. Document generation

  4. Post-processing

  5. Writing to file

3.1. Pre-processing

The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

3.2. Parsing

After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

# # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
3. Processing pipeline
3. Processing pipeline
The generation of output follows the same pipeline for all output formats:
  1. Pre-processing
  2. Parsing
  3. Document generation
  4. Post-processing
  5. Writing to file
3.1. Pre-processing
The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
3.2. Parsing
After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
Chunk #2:
x = 1 // 3
-y = 2 // 5
Chunk #3:
When adding `x` and `y` together we obtain a new rational number:
Chunk #4:
z = x + y
It is then up to the Document generation step to decide how these chunks should be treated.
Custom control over chunk splits
Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
x = 1 // 3
+y = 2 // 5
Chunk #3:
When adding `x` and `y` together we obtain a new rational number:
Chunk #4:
z = x + y
It is then up to the Document generation step to decide how these chunks should be treated.
Custom control over chunk splits
Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
The example above would result in two consecutive code-chunks.
Tip
The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
3.3. Document generation
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, Notebook Output and Script Output. Using the default settings, the following is happening:
  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
  • Script output: markdown chunks are discarded, code chunks are printed as-is.
3.4. Post-processing
When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
3.5. Writing to file
The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

+z = x + y

The example above would result in two consecutive code-chunks.

Tip

The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

3.3. Document generation

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, Notebook Output and Script Output. Using the default settings, the following is happening:

  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),

  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,

  • Script output: markdown chunks are discarded, code chunks are printed as-is.

3.4. Post-processing

When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

3.5. Writing to file

The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

\ No newline at end of file diff --git a/v0.2.2/search.html b/v0.2.2/search.html index 674f80b..e549140 100644 --- a/v0.2.2/search.html +++ b/v0.2.2/search.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
Search

Search

Number of results: loading...

    +Search · Literate.jl
    Search

    Search

    Number of results: loading...

      \ No newline at end of file diff --git a/v0.3.0/customprocessing.html b/v0.3.0/customprocessing.html index 96726fb..b03b48f 100644 --- a/v0.3.0/customprocessing.html +++ b/v0.3.0/customprocessing.html @@ -1,8 +1,49 @@ - -5. Custom pre- and post-processing · Literate.jl
      5. Custom pre- and post-processing

      5. Custom pre- and post-processing

      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

      # # Example
+5. Custom pre- and post-processing · Literate.jl
      5. Custom pre- and post-processing
      5. Custom pre- and post-processing
      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
      # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
      where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
      function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
      
+end

      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:

      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
      \ No newline at end of file diff --git a/v0.3.0/documenter.html b/v0.3.0/documenter.html index 56f688d..fd832f3 100644 --- a/v0.3.0/documenter.html +++ b/v0.3.0/documenter.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
      6. Interaction with Documenter.jl

      6. Interaction with Documenter.jl

      Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

      Literate.markdown:

      • The default code fence will change from
        ```julia
+6. Interaction with Documenter.jl · Literate.jl
        6. Interaction with Documenter.jl
        6. Interaction with Documenter.jl
        Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
        Literate.markdown:
        • The default code fence will change from
          ```julia
 # code
 ```
          to Documenters @example blocks:
          ```@examples $(name)
 # code
-```
        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
          ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
        Literate.notebook:
        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
        • Documenter style markdown math
          ```math
+```
        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
          ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
        Literate.notebook:
        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
        • Documenter style markdown math
          ```math
 \int f dx
 ```
          is replaced with notebook compatible
          \begin{equation}
 \int f dx
-\end{equation}
        Literate.script:
        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
        
+\end{equation}

      Literate.script:

      • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
      \ No newline at end of file diff --git a/v0.3.0/fileformat.html b/v0.3.0/fileformat.html index a1d454a..7d2615f 100644 --- a/v0.3.0/fileformat.html +++ b/v0.3.0/fileformat.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
      2. File Format

      2. File Format

      The source file format for Literate 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.

      2.1. Syntax

      The basic syntax is simple:

      • lines starting with # are treated as markdown,
      • all other lines are treated as julia code.

      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

      Lets look at a simple example:

      # # Rational numbers
+2. File Format · Literate.jl
      2. File Format
      2. File Format
      The source file format for Literate 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.
      2.1. Syntax
      The basic syntax is simple:
      • lines starting with # are treated as markdown,
      • all other lines are treated as julia code.
      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
      Lets look at a simple example:
      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
      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 (for example in the test/runtests.jl script, to include the example in the test suite).
      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
      For simple use this is all you need to know. The following additional special syntax can also be used:
      There is also some default convenience replacements that will always be performed, see Default Replacements.
      2.2. Filtering Lines
      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
      • #md: line exclusive to markdown output,
      • #nb: line exclusive to notebook output,
      • #jl: line exclusive to script output,
      • #src: line exclusive to the source code and thus filtered out unconditionally.
      Lines starting with one of these tokens are filtered out in the preprocessing step.
      Suppose, for example, that we want to include a docstring within a @docs block 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:
      #md # ```@docs
+z = x + y
      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 (for example in the test/runtests.jl script, to include the example in the test suite).
      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
      For simple use this is all you need to know. The following additional special syntax can also be used:
      There is also some default convenience replacements that will always be performed, see Default Replacements.
      2.2. Filtering Lines
      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
      • #md: line exclusive to markdown output,
      • #nb: line exclusive to notebook output,
      • #jl: line exclusive to script output,
      • #src: line exclusive to the source code and thus filtered out unconditionally.
      Lines starting with one of these tokens are filtered out in the preprocessing step.
      Suppose, for example, that we want to include a docstring within a @docs block 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:
      #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 the leading #md from the lines. Beware that the space after the tag is also removed.
      The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
      using Test                      #src
-@test result == expected_result #src
      2.3. Default Replacements
      The following convenience "macros" are always expanded:
      • @__NAME__
        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
      • @__REPO__ROOT_URL__
        expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
      • @__NBVIEWER_ROOT_URL__
        expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
      
+@test result == expected_result #src

      2.3. Default Replacements

      The following convenience "macros" are always expanded:

      • @__NAME__

        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

      • @__REPO__ROOT_URL__

        expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

      • @__NBVIEWER_ROOT_URL__

        expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

      \ No newline at end of file diff --git a/v0.3.0/generated/example.html b/v0.3.0/generated/example.html index e81fa9a..f413939 100644 --- a/v0.3.0/generated/example.html +++ b/v0.3.0/generated/example.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
      7. Example

      7. Example

      This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

      Basic syntax

      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

      x = 1//3
-y = 2//5
      2//5

      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

      • This line starts with #md and is thus only visible in the markdown output.

      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

      x + y
      11//15
      x * y
      2//15

      Output Capturing

      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

      function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
      7. Example
      7. Example
      This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
      Basic syntax
      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
      x = 1//3
+y = 2//5
      2//5
      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
      • This line starts with #md and is thus only visible in the markdown output.
      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
      x + y
      11//15
      x * y
      2//15
      Output Capturing
      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
      function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,121 +51,55 @@ foo()
      This string is printed to std
  1
  2
  3
- 4
      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
      using Plots
+ 4
      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
      using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
      
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   554.571,259.674 555.097,256.559 555.622,253.423 556.148,250.268 556.674,247.094 557.2,243.902 557.725,240.694 558.251,237.471 558.777,234.234 559.302,230.984 
   559.828,227.723 560.354,224.45 560.88,221.169 561.405,217.879 561.931,214.582 562.457,211.279 562.982,207.972 563.508,204.661 564.034,201.347 564.56,198.032 
   
-  "/>
-
   554.571,33.5209 555.097,32.3871 555.622,31.3124 556.148,30.297 556.674,29.3413 557.2,28.4457 557.725,27.6104 558.251,26.8359 558.777,26.1222 559.302,25.4698 
   559.828,24.8788 560.354,24.3495 560.88,23.8819 561.405,23.4764 561.931,23.133 562.457,22.8519 562.982,22.6332 563.508,22.4769 564.034,22.3831 564.56,22.3518 
   
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
      Custom processing
      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
      z = 1.0 + 2.0im
      1.0 + 2.0im
      Documenter.jl interaction
      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
      This page was generated using Literate.jl.
      
+  " style="stroke:#e26f46; stroke-width:1; stroke-opacity:1; fill:none">y2

      Custom processing

      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

      z = 1.0 + 2.0im
      1.0 + 2.0im

      Documenter.jl interaction

      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

      This page was generated using Literate.jl.

      \ No newline at end of file diff --git a/v0.3.0/index.html b/v0.3.0/index.html index 19e53bb..1c9a3a6 100644 --- a/v0.3.0/index.html +++ b/v0.3.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
      1. Introduction

      1. Introduction

      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

      What?

      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

      Why?

      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

      It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

      +1. Introduction · Literate.jl
      1. Introduction

      1. Introduction

      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

      What?

      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

      Why?

      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

      It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

      \ No newline at end of file diff --git a/v0.3.0/outputformats.html b/v0.3.0/outputformats.html index 74cfd45..fc194aa 100644 --- a/v0.3.0/outputformats.html +++ b/v0.3.0/outputformats.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
      4. Output Formats

      4. Output Formats

      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

      # # Rational numbers
+4. Output Formats · Literate.jl
      4. Output Formats
      4. Output Formats
      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
      and see how this is rendered in each of the output formats.
      4.1. Markdown Output
      The (default) markdown output of the source snippet above is as follows
      ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
      and see how this is rendered in each of the output formats.
      4.1. Markdown Output
      The (default) markdown output of the source snippet above is as follows
      ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
      Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
      Literate.markdown — Function.
      Literate.markdown(inputfile, outputdir; kwargs...)
      Generate a markdown file from inputfile and write the result to the directoryoutputdir.
      Keyword arguments:
      • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
      • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
      • codefence: A Pair of opening and closing code fence. Defaults to
        "```@example $(name)" => "```"
        if documenter = true and
        "```julia" => "```"
        if documenter = false.
      source
      4.2. Notebook Output
      The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
      Literate.notebook — Function.
      Literate.notebook(inputfile, outputdir; kwargs...)
      Generate a notebook from inputfile and write the result to outputdir.
      Keyword arguments:
      • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
      • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
      source
      4.3. Script Output
      The (default) script output of the source snippet above is as follows
      x = 1//3
+```
      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
      Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
      Literate.markdown — Function.
      Literate.markdown(inputfile, outputdir; kwargs...)
      Generate a markdown file from inputfile and write the result to the directoryoutputdir.
      Keyword arguments:
      • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
      • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
      • codefence: A Pair of opening and closing code fence. Defaults to
        "```@example $(name)" => "```"
        if documenter = true and
        "```julia" => "```"
        if documenter = false.
      source
      4.2. Notebook Output
      The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
      Literate.notebook — Function.
      Literate.notebook(inputfile, outputdir; kwargs...)
      Generate a notebook from inputfile and write the result to outputdir.
      Keyword arguments:
      • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
      • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
      source
      4.3. Script Output
      The (default) script output of the source snippet above is as follows
      x = 1//3
 
 y = 2//5
 
-z = x + y
      We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
      Literate.script — Function.
      Literate.script(inputfile, outputdir; kwargs...)
      Generate a plain script file from inputfile and write the result to outputdir.
      Keyword arguments:
      • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
      • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
      source
      
+z = x + y

      We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

      Literate.script — Function.
      Literate.script(inputfile, outputdir; kwargs...)

      Generate a plain script file from inputfile and write the result to outputdir.

      Keyword arguments:

      • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
      • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
      source
      \ No newline at end of file diff --git a/v0.3.0/pipeline.html b/v0.3.0/pipeline.html index f2071db..0a01b69 100644 --- a/v0.3.0/pipeline.html +++ b/v0.3.0/pipeline.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
      3. Processing pipeline

      3. Processing pipeline

      The generation of output follows the same pipeline for all output formats:

      1. Pre-processing
      2. Parsing
      3. Document generation
      4. Post-processing
      5. Writing to file

      3.1. Pre-processing

      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

      3.2. Parsing

      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

      # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
      3. Processing pipeline
      3. Processing pipeline
      The generation of output follows the same pipeline for all output formats:
      1. Pre-processing
      2. Parsing
      3. Document generation
      4. Post-processing
      5. Writing to file
      3.1. Pre-processing
      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
      3.2. Parsing
      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
      Chunk #2:
      x = 1 // 3
-y = 2 // 5
      Chunk #3:
      When adding `x` and `y` together we obtain a new rational number:
      Chunk #4:
      z = x + y
      It is then up to the Document generation step to decide how these chunks should be treated.
      Custom control over chunk splits
      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
      x = 1 // 3
+y = 2 // 5
      Chunk #3:
      When adding `x` and `y` together we obtain a new rational number:
      Chunk #4:
      z = x + y
      It is then up to the Document generation step to decide how these chunks should be treated.
      Custom control over chunk splits
      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
      x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
      The example above would result in two consecutive code-chunks.
      Tip
      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
      3.3. Document generation
      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, Notebook Output and Script Output. Using the default settings, the following is happening:
      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
      • Script output: markdown chunks are discarded, code chunks are printed as-is.
      3.4. Post-processing
      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
      3.5. Writing to file
      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
      
+z = x + y

      The example above would result in two consecutive code-chunks.

      Tip

      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

      3.3. Document generation

      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, Notebook Output and Script Output. Using the default settings, the following is happening:

      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
      • Script output: markdown chunks are discarded, code chunks are printed as-is.

      3.4. Post-processing

      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

      3.5. Writing to file

      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

      \ No newline at end of file diff --git a/v0.3.0/search.html b/v0.3.0/search.html index 674f80b..e549140 100644 --- a/v0.3.0/search.html +++ b/v0.3.0/search.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
      Search

      Search

      Number of results: loading...

        +Search · Literate.jl
        Search

        Search

        Number of results: loading...

          \ No newline at end of file diff --git a/v1.0.0/customprocessing.html b/v1.0.0/customprocessing.html index 749ceca..ab618a3 100644 --- a/v1.0.0/customprocessing.html +++ b/v1.0.0/customprocessing.html @@ -1,8 +1,49 @@ - -5. Custom pre- and post-processing · Literate.jl
          5. Custom pre- and post-processing

          5. Custom pre- and post-processing

          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

          # # Example
+5. Custom pre- and post-processing · Literate.jl
          5. Custom pre- and post-processing
          5. Custom pre- and post-processing
          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
          # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
          where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
          function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
          
+end

          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:

          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
          \ No newline at end of file diff --git a/v1.0.0/documenter.html b/v1.0.0/documenter.html index 7a431f3..3fabfab 100644 --- a/v1.0.0/documenter.html +++ b/v1.0.0/documenter.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
          6. Interaction with Documenter.jl

          6. Interaction with Documenter.jl

          Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

          Literate.markdown:

          • The default code fence will change from
            ```julia
+6. Interaction with Documenter.jl · Literate.jl
            6. Interaction with Documenter.jl
            6. Interaction with Documenter.jl
            Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
            Literate.markdown:
            • The default code fence will change from
              ```julia
 # code
 ```
              to Documenters @example blocks:
              ```@examples $(name)
 # code
-```
            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
              ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
            Literate.notebook:
            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
            • Documenter style markdown math
              ```math
+```
            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
              ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
            Literate.notebook:
            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
            • Documenter style markdown math
              ```math
 \int f dx
 ```
              is replaced with notebook compatible
              \begin{equation}
 \int f dx
-\end{equation}
            Literate.script:
            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
            
+\end{equation}

          Literate.script:

          • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
          \ No newline at end of file diff --git a/v1.0.0/fileformat.html b/v1.0.0/fileformat.html index 8a24e34..a02baee 100644 --- a/v1.0.0/fileformat.html +++ b/v1.0.0/fileformat.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
          2. File Format

          2. File Format

          The source file format for Literate 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.

          2.1. Syntax

          The basic syntax is simple:

          • lines starting with # are treated as markdown,
          • all other lines are treated as julia code.

          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

          Lets look at a simple example:

          # # Rational numbers
+2. File Format · Literate.jl
          2. File Format
          2. File Format
          The source file format for Literate 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.
          2.1. Syntax
          The basic syntax is simple:
          • lines starting with # are treated as markdown,
          • all other lines are treated as julia code.
          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
          Lets look at a simple example:
          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
          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 (for example in the test/runtests.jl script, to include the example in the test suite).
          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
          For simple use this is all you need to know. The following additional special syntax can also be used:
          There is also some default convenience replacements that will always be performed, see Default Replacements.
          2.2. Filtering Lines
          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
          • #md: line exclusive to markdown output,
          • #nb: line exclusive to notebook output,
          • #jl: line exclusive to script output,
          • #src: line exclusive to the source code and thus filtered out unconditionally.
          Lines starting with one of these tokens are filtered out in the preprocessing step.
          Suppose, for example, that we want to include a docstring within a @docs block 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:
          #md # ```@docs
+z = x + y
          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 (for example in the test/runtests.jl script, to include the example in the test suite).
          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
          For simple use this is all you need to know. The following additional special syntax can also be used:
          There is also some default convenience replacements that will always be performed, see Default Replacements.
          2.2. Filtering Lines
          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
          • #md: line exclusive to markdown output,
          • #nb: line exclusive to notebook output,
          • #jl: line exclusive to script output,
          • #src: line exclusive to the source code and thus filtered out unconditionally.
          Lines starting with one of these tokens are filtered out in the preprocessing step.
          Suppose, for example, that we want to include a docstring within a @docs block 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:
          #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 the leading #md from the lines. Beware that the space after the tag is also removed.
          The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
          using Test                      #src
-@test result == expected_result #src
          2.3. Default Replacements
          The following convenience "macros" are always expanded:
          • @__NAME__
            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
          • @__REPO__ROOT_URL__
            expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
          • @__NBVIEWER_ROOT_URL__
            expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
          
+@test result == expected_result #src

          2.3. Default Replacements

          The following convenience "macros" are always expanded:

          • @__NAME__

            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

          • @__REPO__ROOT_URL__

            expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

          • @__NBVIEWER_ROOT_URL__

            expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

          \ No newline at end of file diff --git a/v1.0.0/generated/example.html b/v1.0.0/generated/example.html index c6095ec..3216229 100644 --- a/v1.0.0/generated/example.html +++ b/v1.0.0/generated/example.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
          7. Example

          7. Example

          This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

          Basic syntax

          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

          x = 1//3
-y = 2//5
          2//5

          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

          • This line starts with #md and is thus only visible in the markdown output.

          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

          x + y
          11//15
          x * y
          2//15

          Output Capturing

          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

          function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
          7. Example
          7. Example
          This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
          Basic syntax
          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
          x = 1//3
+y = 2//5
          2//5
          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
          • This line starts with #md and is thus only visible in the markdown output.
          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
          x + y
          11//15
          x * y
          2//15
          Output Capturing
          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
          function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,121 +51,55 @@ foo()
          This string is printed to std
  1
  2
  3
- 4
          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
          using Plots
+ 4
          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
          using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
          
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   554.571,259.674 555.097,256.559 555.622,253.423 556.148,250.268 556.674,247.094 557.2,243.902 557.725,240.694 558.251,237.471 558.777,234.234 559.302,230.984 
   559.828,227.723 560.354,224.45 560.88,221.169 561.405,217.879 561.931,214.582 562.457,211.279 562.982,207.972 563.508,204.661 564.034,201.347 564.56,198.032 
   
-  "/>
-
   554.571,33.5209 555.097,32.3871 555.622,31.3124 556.148,30.297 556.674,29.3413 557.2,28.4457 557.725,27.6104 558.251,26.8359 558.777,26.1222 559.302,25.4698 
   559.828,24.8788 560.354,24.3495 560.88,23.8819 561.405,23.4764 561.931,23.133 562.457,22.8519 562.982,22.6332 563.508,22.4769 564.034,22.3831 564.56,22.3518 
   
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
          Custom processing
          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
          z = 1.0 + 2.0im
          1.0 + 2.0im
          Documenter.jl interaction
          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
          This page was generated using Literate.jl.
          
+  " style="stroke:#e26f46; stroke-width:1; stroke-opacity:1; fill:none">y2

          Custom processing

          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

          z = 1.0 + 2.0im
          1.0 + 2.0im

          Documenter.jl interaction

          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

          This page was generated using Literate.jl.

          \ No newline at end of file diff --git a/v1.0.0/index.html b/v1.0.0/index.html index 89d2480..6a6126a 100644 --- a/v1.0.0/index.html +++ b/v1.0.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
          1. Introduction

          1. Introduction

          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

          What?

          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

          Why?

          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

          It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

          +1. Introduction · Literate.jl
          1. Introduction

          1. Introduction

          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

          What?

          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

          Why?

          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

          It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

          \ No newline at end of file diff --git a/v1.0.0/outputformats.html b/v1.0.0/outputformats.html index 126f2d1..1f9c633 100644 --- a/v1.0.0/outputformats.html +++ b/v1.0.0/outputformats.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
          4. Output Formats

          4. Output Formats

          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

          # # Rational numbers
+4. Output Formats · Literate.jl
          4. Output Formats
          4. Output Formats
          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
          and see how this is rendered in each of the output formats.
          4.1. Markdown Output
          The (default) markdown output of the source snippet above is as follows
          ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
          and see how this is rendered in each of the output formats.
          4.1. Markdown Output
          The (default) markdown output of the source snippet above is as follows
          ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
          Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
          Literate.markdown — Function.
          Literate.markdown(inputfile, outputdir; kwargs...)
          Generate a markdown file from inputfile and write the result to the directoryoutputdir.
          Keyword arguments:
          • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
          • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
          • codefence: A Pair of opening and closing code fence. Defaults to
            "```@example $(name)" => "```"
            if documenter = true and
            "```julia" => "```"
            if documenter = false.
          source
          4.2. Notebook Output
          The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
          Literate.notebook — Function.
          Literate.notebook(inputfile, outputdir; kwargs...)
          Generate a notebook from inputfile and write the result to outputdir.
          Keyword arguments:
          • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
          • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
          source
          4.3. Script Output
          The (default) script output of the source snippet above is as follows
          x = 1//3
+```
          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
          Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
          Literate.markdown — Function.
          Literate.markdown(inputfile, outputdir; kwargs...)
          Generate a markdown file from inputfile and write the result to the directoryoutputdir.
          Keyword arguments:
          • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
          • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
          • codefence: A Pair of opening and closing code fence. Defaults to
            "```@example $(name)" => "```"
            if documenter = true and
            "```julia" => "```"
            if documenter = false.
          source
          4.2. Notebook Output
          The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
          Literate.notebook — Function.
          Literate.notebook(inputfile, outputdir; kwargs...)
          Generate a notebook from inputfile and write the result to outputdir.
          Keyword arguments:
          • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
          • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
          source
          4.3. Script Output
          The (default) script output of the source snippet above is as follows
          x = 1//3
 
 y = 2//5
 
-z = x + y
          We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
          Literate.script — Function.
          Literate.script(inputfile, outputdir; kwargs...)
          Generate a plain script file from inputfile and write the result to outputdir.
          Keyword arguments:
          • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
          • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
          source
          
+z = x + y

          We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

          Literate.script — Function.
          Literate.script(inputfile, outputdir; kwargs...)

          Generate a plain script file from inputfile and write the result to outputdir.

          Keyword arguments:

          • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
          • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
          source
          \ No newline at end of file diff --git a/v1.0.0/pipeline.html b/v1.0.0/pipeline.html index 14c7c0f..bc81974 100644 --- a/v1.0.0/pipeline.html +++ b/v1.0.0/pipeline.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
          3. Processing pipeline

          3. Processing pipeline

          The generation of output follows the same pipeline for all output formats:

          1. Pre-processing
          2. Parsing
          3. Document generation
          4. Post-processing
          5. Writing to file

          3.1. Pre-processing

          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

          3.2. Parsing

          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

          # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
          3. Processing pipeline
          3. Processing pipeline
          The generation of output follows the same pipeline for all output formats:
          1. Pre-processing
          2. Parsing
          3. Document generation
          4. Post-processing
          5. Writing to file
          3.1. Pre-processing
          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
          3.2. Parsing
          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
          Chunk #2:
          x = 1 // 3
-y = 2 // 5
          Chunk #3:
          When adding `x` and `y` together we obtain a new rational number:
          Chunk #4:
          z = x + y
          It is then up to the Document generation step to decide how these chunks should be treated.
          Custom control over chunk splits
          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
          x = 1 // 3
+y = 2 // 5
          Chunk #3:
          When adding `x` and `y` together we obtain a new rational number:
          Chunk #4:
          z = x + y
          It is then up to the Document generation step to decide how these chunks should be treated.
          Custom control over chunk splits
          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
          x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
          The example above would result in two consecutive code-chunks.
          Tip
          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
          3.3. Document generation
          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, Notebook Output and Script Output. Using the default settings, the following is happening:
          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
          • Script output: markdown chunks are discarded, code chunks are printed as-is.
          3.4. Post-processing
          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
          3.5. Writing to file
          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
          
+z = x + y

          The example above would result in two consecutive code-chunks.

          Tip

          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

          3.3. Document generation

          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, Notebook Output and Script Output. Using the default settings, the following is happening:

          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
          • Script output: markdown chunks are discarded, code chunks are printed as-is.

          3.4. Post-processing

          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

          3.5. Writing to file

          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

          \ No newline at end of file diff --git a/v1.0.0/search.html b/v1.0.0/search.html index 67a457d..0757e91 100644 --- a/v1.0.0/search.html +++ b/v1.0.0/search.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
          Search

          Search

          Number of results: loading...

            +Search · Literate.jl
            Search

            Search

            Number of results: loading...

              \ No newline at end of file diff --git a/v1.0.1/customprocessing.html b/v1.0.1/customprocessing.html index 749ceca..ab618a3 100644 --- a/v1.0.1/customprocessing.html +++ b/v1.0.1/customprocessing.html @@ -1,8 +1,49 @@ - -5. Custom pre- and post-processing · Literate.jl
              5. Custom pre- and post-processing

              5. Custom pre- and post-processing

              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

              # # Example
+5. Custom pre- and post-processing · Literate.jl
              5. Custom pre- and post-processing
              5. Custom pre- and post-processing
              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
              # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
              where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
              function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
              
+end

              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:

              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
              \ No newline at end of file diff --git a/v1.0.1/documenter.html b/v1.0.1/documenter.html index 7a431f3..3fabfab 100644 --- a/v1.0.1/documenter.html +++ b/v1.0.1/documenter.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
              6. Interaction with Documenter.jl

              6. Interaction with Documenter.jl

              Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

              Literate.markdown:

              • The default code fence will change from
                ```julia
+6. Interaction with Documenter.jl · Literate.jl
                6. Interaction with Documenter.jl
                6. Interaction with Documenter.jl
                Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                Literate.markdown:
                • The default code fence will change from
                  ```julia
 # code
 ```
                  to Documenters @example blocks:
                  ```@examples $(name)
 # code
-```
                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                  ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                Literate.notebook:
                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                • Documenter style markdown math
                  ```math
+```
                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                  ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                Literate.notebook:
                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                • Documenter style markdown math
                  ```math
 \int f dx
 ```
                  is replaced with notebook compatible
                  \begin{equation}
 \int f dx
-\end{equation}
                Literate.script:
                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                
+\end{equation}

              Literate.script:

              • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
              \ No newline at end of file diff --git a/v1.0.1/fileformat.html b/v1.0.1/fileformat.html index 8a24e34..a02baee 100644 --- a/v1.0.1/fileformat.html +++ b/v1.0.1/fileformat.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
              2. File Format

              2. File Format

              The source file format for Literate 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.

              2.1. Syntax

              The basic syntax is simple:

              • lines starting with # are treated as markdown,
              • all other lines are treated as julia code.

              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

              Lets look at a simple example:

              # # Rational numbers
+2. File Format · Literate.jl
              2. File Format
              2. File Format
              The source file format for Literate 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.
              2.1. Syntax
              The basic syntax is simple:
              • lines starting with # are treated as markdown,
              • all other lines are treated as julia code.
              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
              Lets look at a simple example:
              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
              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 (for example in the test/runtests.jl script, to include the example in the test suite).
              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
              For simple use this is all you need to know. The following additional special syntax can also be used:
              There is also some default convenience replacements that will always be performed, see Default Replacements.
              2.2. Filtering Lines
              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
              • #md: line exclusive to markdown output,
              • #nb: line exclusive to notebook output,
              • #jl: line exclusive to script output,
              • #src: line exclusive to the source code and thus filtered out unconditionally.
              Lines starting with one of these tokens are filtered out in the preprocessing step.
              Suppose, for example, that we want to include a docstring within a @docs block 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:
              #md # ```@docs
+z = x + y
              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 (for example in the test/runtests.jl script, to include the example in the test suite).
              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
              For simple use this is all you need to know. The following additional special syntax can also be used:
              There is also some default convenience replacements that will always be performed, see Default Replacements.
              2.2. Filtering Lines
              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
              • #md: line exclusive to markdown output,
              • #nb: line exclusive to notebook output,
              • #jl: line exclusive to script output,
              • #src: line exclusive to the source code and thus filtered out unconditionally.
              Lines starting with one of these tokens are filtered out in the preprocessing step.
              Suppose, for example, that we want to include a docstring within a @docs block 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:
              #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 the leading #md from the lines. Beware that the space after the tag is also removed.
              The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
              using Test                      #src
-@test result == expected_result #src
              2.3. Default Replacements
              The following convenience "macros" are always expanded:
              • @__NAME__
                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
              • @__REPO__ROOT_URL__
                expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
              • @__NBVIEWER_ROOT_URL__
                expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
              
+@test result == expected_result #src

              2.3. Default Replacements

              The following convenience "macros" are always expanded:

              • @__NAME__

                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

              • @__REPO__ROOT_URL__

                expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

              • @__NBVIEWER_ROOT_URL__

                expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

              \ No newline at end of file diff --git a/v1.0.1/generated/example.html b/v1.0.1/generated/example.html index 51b814a..9404f9c 100644 --- a/v1.0.1/generated/example.html +++ b/v1.0.1/generated/example.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
              7. Example

              7. Example

              This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

              Basic syntax

              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

              x = 1//3
-y = 2//5
              2//5

              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

              • This line starts with #md and is thus only visible in the markdown output.

              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

              x + y
              11//15
              x * y
              2//15

              Output Capturing

              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

              function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
              7. Example
              7. Example
              This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
              Basic syntax
              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
              x = 1//3
+y = 2//5
              2//5
              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
              • This line starts with #md and is thus only visible in the markdown output.
              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
              x + y
              11//15
              x * y
              2//15
              Output Capturing
              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
              function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,121 +51,55 @@ foo()
              This string is printed to std
  1
  2
  3
- 4
              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
              using Plots
+ 4
              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
              using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
              
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   554.571,259.674 555.097,256.559 555.622,253.423 556.148,250.268 556.674,247.094 557.2,243.902 557.725,240.694 558.251,237.471 558.777,234.234 559.302,230.984 
   559.828,227.723 560.354,224.45 560.88,221.169 561.405,217.879 561.931,214.582 562.457,211.279 562.982,207.972 563.508,204.661 564.034,201.347 564.56,198.032 
   
-  "/>
-
   554.571,33.5209 555.097,32.3871 555.622,31.3124 556.148,30.297 556.674,29.3413 557.2,28.4457 557.725,27.6104 558.251,26.8359 558.777,26.1222 559.302,25.4698 
   559.828,24.8788 560.354,24.3495 560.88,23.8819 561.405,23.4764 561.931,23.133 562.457,22.8519 562.982,22.6332 563.508,22.4769 564.034,22.3831 564.56,22.3518 
   
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
              Custom processing
              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
              z = 1.0 + 2.0im
              1.0 + 2.0im
              Documenter.jl interaction
              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
              This page was generated using Literate.jl.
              
+  " style="stroke:#e26f46; stroke-width:1; stroke-opacity:1; fill:none">y2

              Custom processing

              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

              z = 1.0 + 2.0im
              1.0 + 2.0im

              Documenter.jl interaction

              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

              This page was generated using Literate.jl.

              \ No newline at end of file diff --git a/v1.0.1/index.html b/v1.0.1/index.html index 89d2480..6a6126a 100644 --- a/v1.0.1/index.html +++ b/v1.0.1/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
              1. Introduction

              1. Introduction

              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

              What?

              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

              The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

              Why?

              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

              It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

              +1. Introduction · Literate.jl
              1. Introduction

              1. Introduction

              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

              What?

              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

              The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

              Why?

              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

              It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

              \ No newline at end of file diff --git a/v1.0.1/outputformats.html b/v1.0.1/outputformats.html index 9a9d078..a91e335 100644 --- a/v1.0.1/outputformats.html +++ b/v1.0.1/outputformats.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
              4. Output Formats

              4. Output Formats

              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

              # # Rational numbers
+4. Output Formats · Literate.jl
              4. Output Formats
              4. Output Formats
              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
              and see how this is rendered in each of the output formats.
              4.1. Markdown Output
              The (default) markdown output of the source snippet above is as follows
              ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
              and see how this is rendered in each of the output formats.
              4.1. Markdown Output
              The (default) markdown output of the source snippet above is as follows
              ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
              Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
              Literate.markdown — Function.
              Literate.markdown(inputfile, outputdir; kwargs...)
              Generate a markdown file from inputfile and write the result to the directoryoutputdir.
              Keyword arguments:
              • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
              • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
              • codefence: A Pair of opening and closing code fence. Defaults to
                "```@example $(name)" => "```"
                if documenter = true and
                "```julia" => "```"
                if documenter = false.
              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
              source
              4.2. Notebook Output
              The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
              Literate.notebook — Function.
              Literate.notebook(inputfile, outputdir; kwargs...)
              Generate a notebook from inputfile and write the result to outputdir.
              Keyword arguments:
              • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
              • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
              source
              4.3. Script Output
              The (default) script output of the source snippet above is as follows
              x = 1//3
+```
              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
              Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
              Literate.markdown — Function.
              Literate.markdown(inputfile, outputdir; kwargs...)
              Generate a markdown file from inputfile and write the result to the directoryoutputdir.
              Keyword arguments:
              • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
              • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
              • codefence: A Pair of opening and closing code fence. Defaults to
                "```@example $(name)" => "```"
                if documenter = true and
                "```julia" => "```"
                if documenter = false.
              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
              source
              4.2. Notebook Output
              The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
              Literate.notebook — Function.
              Literate.notebook(inputfile, outputdir; kwargs...)
              Generate a notebook from inputfile and write the result to outputdir.
              Keyword arguments:
              • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
              • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
              source
              4.3. Script Output
              The (default) script output of the source snippet above is as follows
              x = 1//3
 
 y = 2//5
 
-z = x + y
              We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
              Literate.script — Function.
              Literate.script(inputfile, outputdir; kwargs...)
              Generate a plain script file from inputfile and write the result to outputdir.
              Keyword arguments:
              • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
              • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
              source
              
+z = x + y

              We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

              Literate.script — Function.
              Literate.script(inputfile, outputdir; kwargs...)

              Generate a plain script file from inputfile and write the result to outputdir.

              Keyword arguments:

              • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
              • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
              source
              \ No newline at end of file diff --git a/v1.0.1/pipeline.html b/v1.0.1/pipeline.html index 14c7c0f..bc81974 100644 --- a/v1.0.1/pipeline.html +++ b/v1.0.1/pipeline.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
              3. Processing pipeline

              3. Processing pipeline

              The generation of output follows the same pipeline for all output formats:

              1. Pre-processing
              2. Parsing
              3. Document generation
              4. Post-processing
              5. Writing to file

              3.1. Pre-processing

              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

              3.2. Parsing

              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

              # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
              3. Processing pipeline
              3. Processing pipeline
              The generation of output follows the same pipeline for all output formats:
              1. Pre-processing
              2. Parsing
              3. Document generation
              4. Post-processing
              5. Writing to file
              3.1. Pre-processing
              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
              3.2. Parsing
              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
              Chunk #2:
              x = 1 // 3
-y = 2 // 5
              Chunk #3:
              When adding `x` and `y` together we obtain a new rational number:
              Chunk #4:
              z = x + y
              It is then up to the Document generation step to decide how these chunks should be treated.
              Custom control over chunk splits
              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
              x = 1 // 3
+y = 2 // 5
              Chunk #3:
              When adding `x` and `y` together we obtain a new rational number:
              Chunk #4:
              z = x + y
              It is then up to the Document generation step to decide how these chunks should be treated.
              Custom control over chunk splits
              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
              x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
              The example above would result in two consecutive code-chunks.
              Tip
              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
              3.3. Document generation
              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, Notebook Output and Script Output. Using the default settings, the following is happening:
              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
              • Script output: markdown chunks are discarded, code chunks are printed as-is.
              3.4. Post-processing
              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
              3.5. Writing to file
              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
              
+z = x + y

              The example above would result in two consecutive code-chunks.

              Tip

              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

              3.3. Document generation

              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, Notebook Output and Script Output. Using the default settings, the following is happening:

              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
              • Script output: markdown chunks are discarded, code chunks are printed as-is.

              3.4. Post-processing

              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

              3.5. Writing to file

              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

              \ No newline at end of file diff --git a/v1.0.1/search.html b/v1.0.1/search.html index 67a457d..0757e91 100644 --- a/v1.0.1/search.html +++ b/v1.0.1/search.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
              Search

              Search

              Number of results: loading...

                +Search · Literate.jl
                Search

                Search

                Number of results: loading...

                  \ No newline at end of file diff --git a/v1.0.2/customprocessing.html b/v1.0.2/customprocessing.html index 749ceca..ab618a3 100644 --- a/v1.0.2/customprocessing.html +++ b/v1.0.2/customprocessing.html @@ -1,8 +1,49 @@ - -5. Custom pre- and post-processing · Literate.jl
                  5. Custom pre- and post-processing

                  5. Custom pre- and post-processing

                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                  # # Example
+5. Custom pre- and post-processing · Literate.jl
                  5. Custom pre- and post-processing
                  5. Custom pre- and post-processing
                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                  # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                  where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                  function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                  
+end

                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:

                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                  \ No newline at end of file diff --git a/v1.0.2/documenter.html b/v1.0.2/documenter.html index 7a431f3..3fabfab 100644 --- a/v1.0.2/documenter.html +++ b/v1.0.2/documenter.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                  6. Interaction with Documenter.jl

                  6. Interaction with Documenter.jl

                  Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                  Literate.markdown:

                  • The default code fence will change from
                    ```julia
+6. Interaction with Documenter.jl · Literate.jl
                    6. Interaction with Documenter.jl
                    6. Interaction with Documenter.jl
                    Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                    Literate.markdown:
                    • The default code fence will change from
                      ```julia
 # code
 ```
                      to Documenters @example blocks:
                      ```@examples $(name)
 # code
-```
                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                      ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                    Literate.notebook:
                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                    • Documenter style markdown math
                      ```math
+```
                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                      ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                    Literate.notebook:
                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                    • Documenter style markdown math
                      ```math
 \int f dx
 ```
                      is replaced with notebook compatible
                      \begin{equation}
 \int f dx
-\end{equation}
                    Literate.script:
                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                    
+\end{equation}

                  Literate.script:

                  • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                  \ No newline at end of file diff --git a/v1.0.2/fileformat.html b/v1.0.2/fileformat.html index 8a24e34..a02baee 100644 --- a/v1.0.2/fileformat.html +++ b/v1.0.2/fileformat.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                  2. File Format

                  2. File Format

                  The source file format for Literate 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.

                  2.1. Syntax

                  The basic syntax is simple:

                  • lines starting with # are treated as markdown,
                  • all other lines are treated as julia code.

                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                  Lets look at a simple example:

                  # # Rational numbers
+2. File Format · Literate.jl
                  2. File Format
                  2. File Format
                  The source file format for Literate 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.
                  2.1. Syntax
                  The basic syntax is simple:
                  • lines starting with # are treated as markdown,
                  • all other lines are treated as julia code.
                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                  Lets look at a simple example:
                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                  For simple use this is all you need to know. The following additional special syntax can also be used:
                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                  2.2. Filtering Lines
                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                  • #md: line exclusive to markdown output,
                  • #nb: line exclusive to notebook output,
                  • #jl: line exclusive to script output,
                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                  Lines starting with one of these tokens are filtered out in the preprocessing step.
                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                  #md # ```@docs
+z = x + y
                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                  For simple use this is all you need to know. The following additional special syntax can also be used:
                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                  2.2. Filtering Lines
                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                  • #md: line exclusive to markdown output,
                  • #nb: line exclusive to notebook output,
                  • #jl: line exclusive to script output,
                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                  Lines starting with one of these tokens are filtered out in the preprocessing step.
                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                  #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                  The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                  using Test                      #src
-@test result == expected_result #src
                  2.3. Default Replacements
                  The following convenience "macros" are always expanded:
                  • @__NAME__
                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                  • @__REPO__ROOT_URL__
                    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
                  • @__NBVIEWER_ROOT_URL__
                    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                  
+@test result == expected_result #src

                  2.3. Default Replacements

                  The following convenience "macros" are always expanded:

                  • @__NAME__

                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                  • @__REPO__ROOT_URL__

                    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

                  • @__NBVIEWER_ROOT_URL__

                    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                  \ No newline at end of file diff --git a/v1.0.2/generated/example.html b/v1.0.2/generated/example.html index b9c6100..245736f 100644 --- a/v1.0.2/generated/example.html +++ b/v1.0.2/generated/example.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                  7. Example

                  7. Example

                  This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                  Basic syntax

                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                  x = 1//3
-y = 2//5
                  2//5

                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                  • This line starts with #md and is thus only visible in the markdown output.

                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                  x + y
                  11//15
                  x * y
                  2//15

                  Output Capturing

                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                  function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                  7. Example
                  7. Example
                  This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                  Basic syntax
                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                  x = 1//3
+y = 2//5
                  2//5
                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                  • This line starts with #md and is thus only visible in the markdown output.
                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                  x + y
                  11//15
                  x * y
                  2//15
                  Output Capturing
                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                  function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,121 +51,55 @@ foo()
                  This string is printed to std
  1
  2
  3
- 4
                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                  using Plots
+ 4
                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                  using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                  
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   554.571,259.674 555.097,256.559 555.622,253.423 556.148,250.268 556.674,247.094 557.2,243.902 557.725,240.694 558.251,237.471 558.777,234.234 559.302,230.984 
   559.828,227.723 560.354,224.45 560.88,221.169 561.405,217.879 561.931,214.582 562.457,211.279 562.982,207.972 563.508,204.661 564.034,201.347 564.56,198.032 
   
-  "/>
-
   554.571,33.5209 555.097,32.3871 555.622,31.3124 556.148,30.297 556.674,29.3413 557.2,28.4457 557.725,27.6104 558.251,26.8359 558.777,26.1222 559.302,25.4698 
   559.828,24.8788 560.354,24.3495 560.88,23.8819 561.405,23.4764 561.931,23.133 562.457,22.8519 562.982,22.6332 563.508,22.4769 564.034,22.3831 564.56,22.3518 
   
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                  Custom processing
                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                  z = 1.0 + 2.0im
                  1.0 + 2.0im
                  Documenter.jl interaction
                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                  This page was generated using Literate.jl.
                  
+  " style="stroke:#e26f46; stroke-width:1; stroke-opacity:1; fill:none">y2

                  Custom processing

                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

                  z = 1.0 + 2.0im
                  1.0 + 2.0im

                  Documenter.jl interaction

                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                  This page was generated using Literate.jl.

                  \ No newline at end of file diff --git a/v1.0.2/index.html b/v1.0.2/index.html index 89d2480..6a6126a 100644 --- a/v1.0.2/index.html +++ b/v1.0.2/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                  1. Introduction

                  1. Introduction

                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                  What?

                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                  The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                  Why?

                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                  It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                  +1. Introduction · Literate.jl
                  1. Introduction

                  1. Introduction

                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                  What?

                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                  The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                  Why?

                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                  It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                  \ No newline at end of file diff --git a/v1.0.2/outputformats.html b/v1.0.2/outputformats.html index 9007a2d..93ee397 100644 --- a/v1.0.2/outputformats.html +++ b/v1.0.2/outputformats.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                  4. Output Formats

                  4. Output Formats

                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                  # # Rational numbers
+4. Output Formats · Literate.jl
                  4. Output Formats
                  4. Output Formats
                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                  and see how this is rendered in each of the output formats.
                  4.1. Markdown Output
                  The (default) markdown output of the source snippet above is as follows
                  ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
                  and see how this is rendered in each of the output formats.
                  4.1. Markdown Output
                  The (default) markdown output of the source snippet above is as follows
                  ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                  Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                  Literate.markdown — Function.
                  Literate.markdown(inputfile, outputdir; kwargs...)
                  Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                  Keyword arguments:
                  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                  • codefence: A Pair of opening and closing code fence. Defaults to
                    "```@example $(name)" => "```"
                    if documenter = true and
                    "```julia" => "```"
                    if documenter = false.
                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                  source
                  4.2. Notebook Output
                  The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                  Literate.notebook — Function.
                  Literate.notebook(inputfile, outputdir; kwargs...)
                  Generate a notebook from inputfile and write the result to outputdir.
                  Keyword arguments:
                  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                  source
                  4.3. Script Output
                  The (default) script output of the source snippet above is as follows
                  x = 1//3
+```
                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                  Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                  Literate.markdown — Function.
                  Literate.markdown(inputfile, outputdir; kwargs...)
                  Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                  Keyword arguments:
                  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                  • codefence: A Pair of opening and closing code fence. Defaults to
                    "```@example $(name)" => "```"
                    if documenter = true and
                    "```julia" => "```"
                    if documenter = false.
                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                  source
                  4.2. Notebook Output
                  The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                  Literate.notebook — Function.
                  Literate.notebook(inputfile, outputdir; kwargs...)
                  Generate a notebook from inputfile and write the result to outputdir.
                  Keyword arguments:
                  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                  source
                  4.3. Script Output
                  The (default) script output of the source snippet above is as follows
                  x = 1//3
 
 y = 2//5
 
-z = x + y
                  We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                  Literate.script — Function.
                  Literate.script(inputfile, outputdir; kwargs...)
                  Generate a plain script file from inputfile and write the result to outputdir.
                  Keyword arguments:
                  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                  source
                  
+z = x + y

                  We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                  Literate.script — Function.
                  Literate.script(inputfile, outputdir; kwargs...)

                  Generate a plain script file from inputfile and write the result to outputdir.

                  Keyword arguments:

                  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                  source
                  \ No newline at end of file diff --git a/v1.0.2/pipeline.html b/v1.0.2/pipeline.html index 14c7c0f..bc81974 100644 --- a/v1.0.2/pipeline.html +++ b/v1.0.2/pipeline.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                  3. Processing pipeline

                  3. Processing pipeline

                  The generation of output follows the same pipeline for all output formats:

                  1. Pre-processing
                  2. Parsing
                  3. Document generation
                  4. Post-processing
                  5. Writing to file

                  3.1. Pre-processing

                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                  3.2. Parsing

                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                  # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                  3. Processing pipeline
                  3. Processing pipeline
                  The generation of output follows the same pipeline for all output formats:
                  1. Pre-processing
                  2. Parsing
                  3. Document generation
                  4. Post-processing
                  5. Writing to file
                  3.1. Pre-processing
                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                  3.2. Parsing
                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                  Chunk #2:
                  x = 1 // 3
-y = 2 // 5
                  Chunk #3:
                  When adding `x` and `y` together we obtain a new rational number:
                  Chunk #4:
                  z = x + y
                  It is then up to the Document generation step to decide how these chunks should be treated.
                  Custom control over chunk splits
                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                  x = 1 // 3
+y = 2 // 5
                  Chunk #3:
                  When adding `x` and `y` together we obtain a new rational number:
                  Chunk #4:
                  z = x + y
                  It is then up to the Document generation step to decide how these chunks should be treated.
                  Custom control over chunk splits
                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                  x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                  The example above would result in two consecutive code-chunks.
                  Tip
                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                  3.3. Document generation
                  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, Notebook Output and Script Output. Using the default settings, the following is happening:
                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                  • Script output: markdown chunks are discarded, code chunks are printed as-is.
                  3.4. Post-processing
                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                  3.5. Writing to file
                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                  
+z = x + y

                  The example above would result in two consecutive code-chunks.

                  Tip

                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                  3.3. Document generation

                  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, Notebook Output and Script Output. Using the default settings, the following is happening:

                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                  • Script output: markdown chunks are discarded, code chunks are printed as-is.

                  3.4. Post-processing

                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                  3.5. Writing to file

                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                  \ No newline at end of file diff --git a/v1.0.2/search.html b/v1.0.2/search.html index 67a457d..0757e91 100644 --- a/v1.0.2/search.html +++ b/v1.0.2/search.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
                  Search

                  Search

                  Number of results: loading...

                    +Search · Literate.jl
                    Search

                    Search

                    Number of results: loading...

                      \ No newline at end of file diff --git a/v1.0.3/customprocessing/index.html b/v1.0.3/customprocessing/index.html index 48adc7c..ba1068a 100644 --- a/v1.0.3/customprocessing/index.html +++ b/v1.0.3/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                      5. Custom pre- and post-processing

                      5. Custom pre- and post-processing

                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                      Example: Adding current date

                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                      # # Example
+5. Custom pre- and post-processing · Literate.jl
                      5. Custom pre- and post-processing
                      5. Custom pre- and post-processing
                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                      Example: Adding current date
                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                      # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                      where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                      function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                      Example: Replacing include calls with included code
                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                      # # Replace includes
+end
                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                      Example: Replacing include calls with included code
                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                      # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                      function replace_includes(str)
+include("file2.jl")
                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                      function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                      (of course replace included with your respective files)
                      Finally, you simply pass this function to e.g. Literate.markdown as
                      Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                      This approach is used for example in the documentation of the Julia package TimeseriesPrediction, see here and here for the generating script
                      
+end

                      (of course replace included with your respective files)

                      Finally, you simply pass this function to e.g. Literate.markdown as

                      Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                      This approach is used for example in the documentation of the Julia package TimeseriesPrediction, see here and here for the generating script

                      \ No newline at end of file diff --git a/v1.0.3/documenter/index.html b/v1.0.3/documenter/index.html index e8b7cb6..452d252 100644 --- a/v1.0.3/documenter/index.html +++ b/v1.0.3/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                      6. Interaction with Documenter.jl

                      6. Interaction with Documenter.jl

                      Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                      Literate.markdown:

                      • The default code fence will change from
                        ```julia
+6. Interaction with Documenter.jl · Literate.jl
                        6. Interaction with Documenter.jl
                        6. Interaction with Documenter.jl
                        Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                        Literate.markdown:
                        • The default code fence will change from
                          ```julia
 # code
 ```
                          to Documenters @example blocks:
                          ```@examples $(name)
 # code
-```
                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                          ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                        Literate.notebook:
                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                        • Documenter style markdown math
                          ```math
+```
                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                          ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                        Literate.notebook:
                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                        • Documenter style markdown math
                          ```math
 \int f dx
 ```
                          is replaced with notebook compatible
                          \begin{equation}
 \int f dx
-\end{equation}
                        Literate.script:
                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                        
+\end{equation}

                      Literate.script:

                      • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                      \ No newline at end of file diff --git a/v1.0.3/fileformat/index.html b/v1.0.3/fileformat/index.html index 6c9695d..0809092 100644 --- a/v1.0.3/fileformat/index.html +++ b/v1.0.3/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                      2. File Format

                      2. File Format

                      The source file format for Literate 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.

                      2.1. Syntax

                      The basic syntax is simple:

                      • lines starting with # are treated as markdown,
                      • all other lines are treated as julia code.

                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                      Lets look at a simple example:

                      # # Rational numbers
+2. File Format · Literate.jl
                      2. File Format
                      2. File Format
                      The source file format for Literate 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.
                      2.1. Syntax
                      The basic syntax is simple:
                      • lines starting with # are treated as markdown,
                      • all other lines are treated as julia code.
                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                      Lets look at a simple example:
                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                      For simple use this is all you need to know. The following additional special syntax can also be used:
                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                      2.2. Filtering Lines
                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                      • #md: line exclusive to markdown output,
                      • #nb: line exclusive to notebook output,
                      • #jl: line exclusive to script output,
                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                      Lines starting with one of these tokens are filtered out in the preprocessing step.
                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                      #md # ```@docs
+z = x + y
                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                      For simple use this is all you need to know. The following additional special syntax can also be used:
                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                      2.2. Filtering Lines
                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                      • #md: line exclusive to markdown output,
                      • #nb: line exclusive to notebook output,
                      • #jl: line exclusive to script output,
                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                      Lines starting with one of these tokens are filtered out in the preprocessing step.
                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                      #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                      The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                      using Test                      #src
-@test result == expected_result #src
                      2.3. Default Replacements
                      The following convenience "macros" are always expanded:
                      • @__NAME__
                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                      • @__REPO__ROOT_URL__
                        expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
                      • @__NBVIEWER_ROOT_URL__
                        expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                      
+@test result == expected_result #src

                      2.3. Default Replacements

                      The following convenience "macros" are always expanded:

                      • @__NAME__

                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                      • @__REPO__ROOT_URL__

                        expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

                      • @__NBVIEWER_ROOT_URL__

                        expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                      \ No newline at end of file diff --git a/v1.0.3/generated/example/index.html b/v1.0.3/generated/example/index.html index 37a2807..52c2fc3 100644 --- a/v1.0.3/generated/example/index.html +++ b/v1.0.3/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                      7. Example

                      7. Example

                      This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                      Basic syntax

                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                      x = 1//3
-y = 2//5
                      2//5

                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                      • This line starts with #md and is thus only visible in the markdown output.

                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                      x + y
                      11//15
                      x * y
                      2//15

                      Output Capturing

                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                      function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                      7. Example
                      7. Example
                      This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                      Basic syntax
                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                      x = 1//3
+y = 2//5
                      2//5
                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                      • This line starts with #md and is thus only visible in the markdown output.
                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                      x + y
                      11//15
                      x * y
                      2//15
                      Output Capturing
                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                      function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,126 +51,55 @@ foo()
                      This string is printed to std
  1
  2
  3
- 4
                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                      using Plots
+ 4
                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                      using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                      
-
-
-  
-    
-  
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   2218.28,1038.69 2220.39,1026.23 2222.49,1013.69 2224.59,1001.07 2226.7,988.374 2228.8,975.608 2230.9,962.777 2233,949.885 2235.11,936.937 2237.21,923.937 
   2239.31,910.891 2241.42,897.802 2243.52,884.675 2245.62,871.516 2247.72,858.328 2249.83,845.117 2251.93,831.886 2254.03,818.642 2256.14,805.388 2258.24,792.13 
   
-  "/>
-
   2218.28,134.083 2220.39,129.549 2222.49,125.25 2224.59,121.188 2226.7,117.365 2228.8,113.783 2230.9,110.442 2233,107.343 2235.11,104.489 2237.21,101.879 
   2239.31,99.5152 2241.42,97.3978 2243.52,95.5278 2245.62,93.9057 2247.72,92.5322 2249.83,91.4077 2251.93,90.5327 2254.03,89.9075 2256.14,89.5323 2258.24,89.4072 
   
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                      Custom processing
                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                      z = 1.0 + 2.0im
                      1.0 + 2.0im
                      Documenter.jl interaction
                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                      This page was generated using Literate.jl.
                      
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2

                      Custom processing

                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

                      z = 1.0 + 2.0im
                      1.0 + 2.0im

                      Documenter.jl interaction

                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                      This page was generated using Literate.jl.

                      \ No newline at end of file diff --git a/v1.0.3/index.html b/v1.0.3/index.html index c7f292e..a14efdc 100644 --- a/v1.0.3/index.html +++ b/v1.0.3/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                      1. Introduction

                      1. Introduction

                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                      What?

                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                      Why?

                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                      It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                      +1. Introduction · Literate.jl
                      1. Introduction

                      1. Introduction

                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                      What?

                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                      Why?

                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                      It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                      \ No newline at end of file diff --git a/v1.0.3/outputformats/index.html b/v1.0.3/outputformats/index.html index d897464..c92692a 100644 --- a/v1.0.3/outputformats/index.html +++ b/v1.0.3/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                      4. Output Formats

                      4. Output Formats

                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                      # # Rational numbers
+4. Output Formats · Literate.jl
                      4. Output Formats
                      4. Output Formats
                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                      and see how this is rendered in each of the output formats.
                      4.1. Markdown Output
                      The (default) markdown output of the source snippet above is as follows
                      ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
                      and see how this is rendered in each of the output formats.
                      4.1. Markdown Output
                      The (default) markdown output of the source snippet above is as follows
                      ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                      Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                      Literate.markdown — Function.
                      Literate.markdown(inputfile, outputdir; kwargs...)
                      Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                      Keyword arguments:
                      • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                      • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                      • codefence: A Pair of opening and closing code fence. Defaults to
                        "```@example $(name)" => "```"
                        if documenter = true and
                        "```julia" => "```"
                        if documenter = false.
                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                      source
                      4.2. Notebook Output
                      The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                      Literate.notebook — Function.
                      Literate.notebook(inputfile, outputdir; kwargs...)
                      Generate a notebook from inputfile and write the result to outputdir.
                      Keyword arguments:
                      • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                      • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                      source
                      4.3. Script Output
                      The (default) script output of the source snippet above is as follows
                      x = 1//3
+```
                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                      Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                      Literate.markdown — Function.
                      Literate.markdown(inputfile, outputdir; kwargs...)
                      Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                      Keyword arguments:
                      • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                      • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                      • codefence: A Pair of opening and closing code fence. Defaults to
                        "```@example $(name)" => "```"
                        if documenter = true and
                        "```julia" => "```"
                        if documenter = false.
                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                      source
                      4.2. Notebook Output
                      The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                      Literate.notebook — Function.
                      Literate.notebook(inputfile, outputdir; kwargs...)
                      Generate a notebook from inputfile and write the result to outputdir.
                      Keyword arguments:
                      • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                      • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                      source
                      4.3. Script Output
                      The (default) script output of the source snippet above is as follows
                      x = 1//3
 
 y = 2//5
 
-z = x + y
                      We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                      Literate.script — Function.
                      Literate.script(inputfile, outputdir; kwargs...)
                      Generate a plain script file from inputfile and write the result to outputdir.
                      Keyword arguments:
                      • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                      • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                      source
                      
+z = x + y

                      We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                      Literate.script — Function.
                      Literate.script(inputfile, outputdir; kwargs...)

                      Generate a plain script file from inputfile and write the result to outputdir.

                      Keyword arguments:

                      • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                      • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                      source
                      \ No newline at end of file diff --git a/v1.0.3/pipeline/index.html b/v1.0.3/pipeline/index.html index 067ff5f..03f7ec6 100644 --- a/v1.0.3/pipeline/index.html +++ b/v1.0.3/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                      3. Processing pipeline

                      3. Processing pipeline

                      The generation of output follows the same pipeline for all output formats:

                      1. Pre-processing
                      2. Parsing
                      3. Document generation
                      4. Post-processing
                      5. Writing to file

                      3.1. Pre-processing

                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                      3.2. Parsing

                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                      # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                      3. Processing pipeline
                      3. Processing pipeline
                      The generation of output follows the same pipeline for all output formats:
                      1. Pre-processing
                      2. Parsing
                      3. Document generation
                      4. Post-processing
                      5. Writing to file
                      3.1. Pre-processing
                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                      3.2. Parsing
                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                      Chunk #2:
                      x = 1 // 3
-y = 2 // 5
                      Chunk #3:
                      When adding `x` and `y` together we obtain a new rational number:
                      Chunk #4:
                      z = x + y
                      It is then up to the Document generation step to decide how these chunks should be treated.
                      Custom control over chunk splits
                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                      x = 1 // 3
+y = 2 // 5
                      Chunk #3:
                      When adding `x` and `y` together we obtain a new rational number:
                      Chunk #4:
                      z = x + y
                      It is then up to the Document generation step to decide how these chunks should be treated.
                      Custom control over chunk splits
                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                      x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                      The example above would result in two consecutive code-chunks.
                      Tip
                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                      3.3. Document generation
                      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, Notebook Output and Script Output. Using the default settings, the following is happening:
                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                      • Script output: markdown chunks are discarded, code chunks are printed as-is.
                      3.4. Post-processing
                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                      3.5. Writing to file
                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                      
+z = x + y

                      The example above would result in two consecutive code-chunks.

                      Tip

                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                      3.3. Document generation

                      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, Notebook Output and Script Output. Using the default settings, the following is happening:

                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                      • Script output: markdown chunks are discarded, code chunks are printed as-is.

                      3.4. Post-processing

                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                      3.5. Writing to file

                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                      \ No newline at end of file diff --git a/v1.0.3/search/index.html b/v1.0.3/search/index.html index 2a66a22..7e10223 100644 --- a/v1.0.3/search/index.html +++ b/v1.0.3/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
                      Search

                      Search

                      Number of results: loading...

                        +Search · Literate.jl
                        Search

                        Search

                        Number of results: loading...

                          \ No newline at end of file diff --git a/v1.0.4/customprocessing/index.html b/v1.0.4/customprocessing/index.html index 48adc7c..ba1068a 100644 --- a/v1.0.4/customprocessing/index.html +++ b/v1.0.4/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                          5. Custom pre- and post-processing

                          5. Custom pre- and post-processing

                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                          Example: Adding current date

                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                          # # Example
+5. Custom pre- and post-processing · Literate.jl
                          5. Custom pre- and post-processing
                          5. Custom pre- and post-processing
                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                          Example: Adding current date
                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                          # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                          where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                          function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                          Example: Replacing include calls with included code
                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                          # # Replace includes
+end
                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                          Example: Replacing include calls with included code
                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                          # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                          function replace_includes(str)
+include("file2.jl")
                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                          function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                          (of course replace included with your respective files)
                          Finally, you simply pass this function to e.g. Literate.markdown as
                          Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                          This approach is used for example in the documentation of the Julia package TimeseriesPrediction, see here and here for the generating script
                          
+end

                          (of course replace included with your respective files)

                          Finally, you simply pass this function to e.g. Literate.markdown as

                          Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                          This approach is used for example in the documentation of the Julia package TimeseriesPrediction, see here and here for the generating script

                          \ No newline at end of file diff --git a/v1.0.4/documenter/index.html b/v1.0.4/documenter/index.html index e8b7cb6..452d252 100644 --- a/v1.0.4/documenter/index.html +++ b/v1.0.4/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                          6. Interaction with Documenter.jl

                          6. Interaction with Documenter.jl

                          Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                          Literate.markdown:

                          • The default code fence will change from
                            ```julia
+6. Interaction with Documenter.jl · Literate.jl
                            6. Interaction with Documenter.jl
                            6. Interaction with Documenter.jl
                            Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                            Literate.markdown:
                            • The default code fence will change from
                              ```julia
 # code
 ```
                              to Documenters @example blocks:
                              ```@examples $(name)
 # code
-```
                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                              ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                            Literate.notebook:
                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                            • Documenter style markdown math
                              ```math
+```
                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                              ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                            Literate.notebook:
                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                            • Documenter style markdown math
                              ```math
 \int f dx
 ```
                              is replaced with notebook compatible
                              \begin{equation}
 \int f dx
-\end{equation}
                            Literate.script:
                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                            
+\end{equation}

                          Literate.script:

                          • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                          \ No newline at end of file diff --git a/v1.0.4/fileformat/index.html b/v1.0.4/fileformat/index.html index 6c9695d..0809092 100644 --- a/v1.0.4/fileformat/index.html +++ b/v1.0.4/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                          2. File Format

                          2. File Format

                          The source file format for Literate 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.

                          2.1. Syntax

                          The basic syntax is simple:

                          • lines starting with # are treated as markdown,
                          • all other lines are treated as julia code.

                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                          Lets look at a simple example:

                          # # Rational numbers
+2. File Format · Literate.jl
                          2. File Format
                          2. File Format
                          The source file format for Literate 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.
                          2.1. Syntax
                          The basic syntax is simple:
                          • lines starting with # are treated as markdown,
                          • all other lines are treated as julia code.
                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                          Lets look at a simple example:
                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                          For simple use this is all you need to know. The following additional special syntax can also be used:
                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                          2.2. Filtering Lines
                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                          • #md: line exclusive to markdown output,
                          • #nb: line exclusive to notebook output,
                          • #jl: line exclusive to script output,
                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                          Lines starting with one of these tokens are filtered out in the preprocessing step.
                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                          #md # ```@docs
+z = x + y
                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                          For simple use this is all you need to know. The following additional special syntax can also be used:
                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                          2.2. Filtering Lines
                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                          • #md: line exclusive to markdown output,
                          • #nb: line exclusive to notebook output,
                          • #jl: line exclusive to script output,
                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                          Lines starting with one of these tokens are filtered out in the preprocessing step.
                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                          #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                          The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                          using Test                      #src
-@test result == expected_result #src
                          2.3. Default Replacements
                          The following convenience "macros" are always expanded:
                          • @__NAME__
                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                          • @__REPO__ROOT_URL__
                            expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
                          • @__NBVIEWER_ROOT_URL__
                            expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                          
+@test result == expected_result #src

                          2.3. Default Replacements

                          The following convenience "macros" are always expanded:

                          • @__NAME__

                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                          • @__REPO__ROOT_URL__

                            expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

                          • @__NBVIEWER_ROOT_URL__

                            expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                          \ No newline at end of file diff --git a/v1.0.4/generated/example/index.html b/v1.0.4/generated/example/index.html index 3626d8c..580045e 100644 --- a/v1.0.4/generated/example/index.html +++ b/v1.0.4/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                          7. Example

                          7. Example

                          This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                          Basic syntax

                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                          x = 1//3
-y = 2//5
                          2//5

                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                          • This line starts with #md and is thus only visible in the markdown output.

                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                          x + y
                          11//15
                          x * y
                          2//15

                          Output Capturing

                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                          function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                          7. Example
                          7. Example
                          This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                          Basic syntax
                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                          x = 1//3
+y = 2//5
                          2//5
                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                          • This line starts with #md and is thus only visible in the markdown output.
                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                          x + y
                          11//15
                          x * y
                          2//15
                          Output Capturing
                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                          function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,126 +51,55 @@ foo()
                          This string is printed to std
  1
  2
  3
- 4
                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                          using Plots
+ 4
                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                          using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                          
-
-
-  
-    
-  
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   2218.28,1038.69 2220.39,1026.23 2222.49,1013.69 2224.59,1001.07 2226.7,988.374 2228.8,975.608 2230.9,962.777 2233,949.885 2235.11,936.937 2237.21,923.937 
   2239.31,910.891 2241.42,897.802 2243.52,884.675 2245.62,871.516 2247.72,858.328 2249.83,845.117 2251.93,831.886 2254.03,818.642 2256.14,805.388 2258.24,792.13 
   
-  "/>
-
   2218.28,134.083 2220.39,129.549 2222.49,125.25 2224.59,121.188 2226.7,117.365 2228.8,113.783 2230.9,110.442 2233,107.343 2235.11,104.489 2237.21,101.879 
   2239.31,99.5152 2241.42,97.3978 2243.52,95.5278 2245.62,93.9057 2247.72,92.5322 2249.83,91.4077 2251.93,90.5327 2254.03,89.9075 2256.14,89.5323 2258.24,89.4072 
   
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                          Custom processing
                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                          z = 1.0 + 2.0im
                          1.0 + 2.0im
                          Documenter.jl interaction
                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                          This page was generated using Literate.jl.
                          
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2

                          Custom processing

                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

                          z = 1.0 + 2.0im
                          1.0 + 2.0im

                          Documenter.jl interaction

                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                          This page was generated using Literate.jl.

                          \ No newline at end of file diff --git a/v1.0.4/index.html b/v1.0.4/index.html index c7f292e..a14efdc 100644 --- a/v1.0.4/index.html +++ b/v1.0.4/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                          1. Introduction

                          1. Introduction

                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                          What?

                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                          Why?

                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                          It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                          +1. Introduction · Literate.jl
                          1. Introduction

                          1. Introduction

                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                          What?

                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                          Why?

                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                          It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                          \ No newline at end of file diff --git a/v1.0.4/outputformats/index.html b/v1.0.4/outputformats/index.html index a956461..335a052 100644 --- a/v1.0.4/outputformats/index.html +++ b/v1.0.4/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                          4. Output Formats

                          4. Output Formats

                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                          # # Rational numbers
+4. Output Formats · Literate.jl
                          4. Output Formats
                          4. Output Formats
                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                          and see how this is rendered in each of the output formats.
                          4.1. Markdown Output
                          The (default) markdown output of the source snippet above is as follows
                          ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
                          and see how this is rendered in each of the output formats.
                          4.1. Markdown Output
                          The (default) markdown output of the source snippet above is as follows
                          ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                          Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                          Literate.markdown — Function.
                          Literate.markdown(inputfile, outputdir; kwargs...)
                          Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                          Keyword arguments:
                          • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                          • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                          • codefence: A Pair of opening and closing code fence. Defaults to
                            "```@example $(name)" => "```"
                            if documenter = true and
                            "```julia" => "```"
                            if documenter = false.
                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                          source
                          4.2. Notebook Output
                          The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                          Literate.notebook — Function.
                          Literate.notebook(inputfile, outputdir; kwargs...)
                          Generate a notebook from inputfile and write the result to outputdir.
                          Keyword arguments:
                          • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                          • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                          source
                          4.3. Script Output
                          The (default) script output of the source snippet above is as follows
                          x = 1//3
+```
                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                          Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                          Literate.markdown — Function.
                          Literate.markdown(inputfile, outputdir; kwargs...)
                          Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                          Keyword arguments:
                          • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                          • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                          • codefence: A Pair of opening and closing code fence. Defaults to
                            "```@example $(name)" => "```"
                            if documenter = true and
                            "```julia" => "```"
                            if documenter = false.
                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                          source
                          4.2. Notebook Output
                          The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                          Literate.notebook — Function.
                          Literate.notebook(inputfile, outputdir; kwargs...)
                          Generate a notebook from inputfile and write the result to outputdir.
                          Keyword arguments:
                          • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                          • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                          source
                          4.3. Script Output
                          The (default) script output of the source snippet above is as follows
                          x = 1//3
 
 y = 2//5
 
-z = x + y
                          We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                          Literate.script — Function.
                          Literate.script(inputfile, outputdir; kwargs...)
                          Generate a plain script file from inputfile and write the result to outputdir.
                          Keyword arguments:
                          • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                          • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                          source
                          
+z = x + y

                          We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                          Literate.script — Function.
                          Literate.script(inputfile, outputdir; kwargs...)

                          Generate a plain script file from inputfile and write the result to outputdir.

                          Keyword arguments:

                          • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                          • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                          source
                          \ No newline at end of file diff --git a/v1.0.4/pipeline/index.html b/v1.0.4/pipeline/index.html index 067ff5f..03f7ec6 100644 --- a/v1.0.4/pipeline/index.html +++ b/v1.0.4/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                          3. Processing pipeline

                          3. Processing pipeline

                          The generation of output follows the same pipeline for all output formats:

                          1. Pre-processing
                          2. Parsing
                          3. Document generation
                          4. Post-processing
                          5. Writing to file

                          3.1. Pre-processing

                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                          3.2. Parsing

                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                          # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                          3. Processing pipeline
                          3. Processing pipeline
                          The generation of output follows the same pipeline for all output formats:
                          1. Pre-processing
                          2. Parsing
                          3. Document generation
                          4. Post-processing
                          5. Writing to file
                          3.1. Pre-processing
                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                          3.2. Parsing
                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                          Chunk #2:
                          x = 1 // 3
-y = 2 // 5
                          Chunk #3:
                          When adding `x` and `y` together we obtain a new rational number:
                          Chunk #4:
                          z = x + y
                          It is then up to the Document generation step to decide how these chunks should be treated.
                          Custom control over chunk splits
                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                          x = 1 // 3
+y = 2 // 5
                          Chunk #3:
                          When adding `x` and `y` together we obtain a new rational number:
                          Chunk #4:
                          z = x + y
                          It is then up to the Document generation step to decide how these chunks should be treated.
                          Custom control over chunk splits
                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                          x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                          The example above would result in two consecutive code-chunks.
                          Tip
                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                          3.3. Document generation
                          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, Notebook Output and Script Output. Using the default settings, the following is happening:
                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                          • Script output: markdown chunks are discarded, code chunks are printed as-is.
                          3.4. Post-processing
                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                          3.5. Writing to file
                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                          
+z = x + y

                          The example above would result in two consecutive code-chunks.

                          Tip

                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                          3.3. Document generation

                          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, Notebook Output and Script Output. Using the default settings, the following is happening:

                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                          • Script output: markdown chunks are discarded, code chunks are printed as-is.

                          3.4. Post-processing

                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                          3.5. Writing to file

                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                          \ No newline at end of file diff --git a/v1.0.4/search/index.html b/v1.0.4/search/index.html index 2a66a22..7e10223 100644 --- a/v1.0.4/search/index.html +++ b/v1.0.4/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
                          Search

                          Search

                          Number of results: loading...

                            +Search · Literate.jl
                            Search

                            Search

                            Number of results: loading...

                              \ No newline at end of file diff --git a/v1.0.5/customprocessing/index.html b/v1.0.5/customprocessing/index.html index 48adc7c..ba1068a 100644 --- a/v1.0.5/customprocessing/index.html +++ b/v1.0.5/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                              5. Custom pre- and post-processing

                              5. Custom pre- and post-processing

                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                              Example: Adding current date

                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                              # # Example
+5. Custom pre- and post-processing · Literate.jl
                              5. Custom pre- and post-processing
                              5. Custom pre- and post-processing
                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                              Example: Adding current date
                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                              # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                              where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                              function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                              Example: Replacing include calls with included code
                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                              # # Replace includes
+end
                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                              Example: Replacing include calls with included code
                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                              # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                              function replace_includes(str)
+include("file2.jl")
                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                              function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                              (of course replace included with your respective files)
                              Finally, you simply pass this function to e.g. Literate.markdown as
                              Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                              This approach is used for example in the documentation of the Julia package TimeseriesPrediction, see here and here for the generating script
                              
+end

                              (of course replace included with your respective files)

                              Finally, you simply pass this function to e.g. Literate.markdown as

                              Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                              This approach is used for example in the documentation of the Julia package TimeseriesPrediction, see here and here for the generating script

                              \ No newline at end of file diff --git a/v1.0.5/documenter/index.html b/v1.0.5/documenter/index.html index e8b7cb6..452d252 100644 --- a/v1.0.5/documenter/index.html +++ b/v1.0.5/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                              6. Interaction with Documenter.jl

                              6. Interaction with Documenter.jl

                              Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                              Literate.markdown:

                              • The default code fence will change from
                                ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                6. Interaction with Documenter.jl
                                6. Interaction with Documenter.jl
                                Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                Literate.markdown:
                                • The default code fence will change from
                                  ```julia
 # code
 ```
                                  to Documenters @example blocks:
                                  ```@examples $(name)
 # code
-```
                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                  ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                Literate.notebook:
                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                • Documenter style markdown math
                                  ```math
+```
                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                  ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                Literate.notebook:
                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                • Documenter style markdown math
                                  ```math
 \int f dx
 ```
                                  is replaced with notebook compatible
                                  \begin{equation}
 \int f dx
-\end{equation}
                                Literate.script:
                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                
+\end{equation}

                              Literate.script:

                              • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                              \ No newline at end of file diff --git a/v1.0.5/fileformat/index.html b/v1.0.5/fileformat/index.html index 6c9695d..0809092 100644 --- a/v1.0.5/fileformat/index.html +++ b/v1.0.5/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                              2. File Format

                              2. File Format

                              The source file format for Literate 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.

                              2.1. Syntax

                              The basic syntax is simple:

                              • lines starting with # are treated as markdown,
                              • all other lines are treated as julia code.

                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                              Lets look at a simple example:

                              # # Rational numbers
+2. File Format · Literate.jl
                              2. File Format
                              2. File Format
                              The source file format for Literate 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.
                              2.1. Syntax
                              The basic syntax is simple:
                              • lines starting with # are treated as markdown,
                              • all other lines are treated as julia code.
                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                              Lets look at a simple example:
                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                              For simple use this is all you need to know. The following additional special syntax can also be used:
                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                              2.2. Filtering Lines
                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                              • #md: line exclusive to markdown output,
                              • #nb: line exclusive to notebook output,
                              • #jl: line exclusive to script output,
                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                              Lines starting with one of these tokens are filtered out in the preprocessing step.
                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                              #md # ```@docs
+z = x + y
                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                              For simple use this is all you need to know. The following additional special syntax can also be used:
                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                              2.2. Filtering Lines
                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                              • #md: line exclusive to markdown output,
                              • #nb: line exclusive to notebook output,
                              • #jl: line exclusive to script output,
                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                              Lines starting with one of these tokens are filtered out in the preprocessing step.
                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                              #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                              The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                              using Test                      #src
-@test result == expected_result #src
                              2.3. Default Replacements
                              The following convenience "macros" are always expanded:
                              • @__NAME__
                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                              • @__REPO__ROOT_URL__
                                expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
                              • @__NBVIEWER_ROOT_URL__
                                expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                              
+@test result == expected_result #src

                              2.3. Default Replacements

                              The following convenience "macros" are always expanded:

                              • @__NAME__

                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                              • @__REPO__ROOT_URL__

                                expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

                              • @__NBVIEWER_ROOT_URL__

                                expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                              \ No newline at end of file diff --git a/v1.0.5/generated/example/index.html b/v1.0.5/generated/example/index.html index 94ede41..6e9ae68 100644 --- a/v1.0.5/generated/example/index.html +++ b/v1.0.5/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                              7. Example

                              7. Example

                              This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                              Basic syntax

                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                              x = 1//3
-y = 2//5
                              2//5

                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                              • This line starts with #md and is thus only visible in the markdown output.

                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                              x + y
                              11//15
                              x * y
                              2//15

                              Output Capturing

                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                              function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                              7. Example
                              7. Example
                              This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.
                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                              Basic syntax
                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                              x = 1//3
+y = 2//5
                              2//5
                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                              • This line starts with #md and is thus only visible in the markdown output.
                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                              x + y
                              11//15
                              x * y
                              2//15
                              Output Capturing
                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                              function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -10,126 +51,55 @@ foo()
                              This string is printed to std
  1
  2
  3
- 4
                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                              using Plots
+ 4
                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                              using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                              
-
-
-  
-    
-  
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   2218.28,1038.69 2220.39,1026.23 2222.49,1013.69 2224.59,1001.07 2226.7,988.374 2228.8,975.608 2230.9,962.777 2233,949.885 2235.11,936.937 2237.21,923.937 
   2239.31,910.891 2241.42,897.802 2243.52,884.675 2245.62,871.516 2247.72,858.328 2249.83,845.117 2251.93,831.886 2254.03,818.642 2256.14,805.388 2258.24,792.13 
   
-  "/>
-
   2218.28,134.083 2220.39,129.549 2222.49,125.25 2224.59,121.188 2226.7,117.365 2228.8,113.783 2230.9,110.442 2233,107.343 2235.11,104.489 2237.21,101.879 
   2239.31,99.5152 2241.42,97.3978 2243.52,95.5278 2245.62,93.9057 2247.72,92.5322 2249.83,91.4077 2251.93,90.5327 2254.03,89.9075 2256.14,89.5323 2258.24,89.4072 
   
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                              Custom processing
                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                              z = 1.0 + 2.0im
                              1.0 + 2.0im
                              Documenter.jl interaction
                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                              This page was generated using Literate.jl.
                              
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2

                              Custom processing

                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

                              z = 1.0 + 2.0im
                              1.0 + 2.0im

                              Documenter.jl interaction

                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                              This page was generated using Literate.jl.

                              \ No newline at end of file diff --git a/v1.0.5/index.html b/v1.0.5/index.html index c7f292e..a14efdc 100644 --- a/v1.0.5/index.html +++ b/v1.0.5/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                              1. Introduction

                              1. Introduction

                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                              What?

                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                              The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                              Why?

                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                              It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                              +1. Introduction · Literate.jl
                              1. Introduction

                              1. Introduction

                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                              What?

                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                              The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                              Why?

                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                              It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                              \ No newline at end of file diff --git a/v1.0.5/outputformats/index.html b/v1.0.5/outputformats/index.html index 8f0d2d4..f67d5c9 100644 --- a/v1.0.5/outputformats/index.html +++ b/v1.0.5/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                              4. Output Formats

                              4. Output Formats

                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                              # # Rational numbers
+4. Output Formats · Literate.jl
                              4. Output Formats
                              4. Output Formats
                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                              and see how this is rendered in each of the output formats.
                              4.1. Markdown Output
                              The (default) markdown output of the source snippet above is as follows
                              ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
                              and see how this is rendered in each of the output formats.
                              4.1. Markdown Output
                              The (default) markdown output of the source snippet above is as follows
                              ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                              Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                              Literate.markdown — Function.
                              Literate.markdown(inputfile, outputdir; kwargs...)
                              Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                              Keyword arguments:
                              • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                              • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                              • codefence: A Pair of opening and closing code fence. Defaults to
                                "```@example $(name)" => "```"
                                if documenter = true and
                                "```julia" => "```"
                                if documenter = false.
                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                              source
                              4.2. Notebook Output
                              The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                              Literate.notebook — Function.
                              Literate.notebook(inputfile, outputdir; kwargs...)
                              Generate a notebook from inputfile and write the result to outputdir.
                              Keyword arguments:
                              • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                              • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                              source
                              4.3. Script Output
                              The (default) script output of the source snippet above is as follows
                              x = 1//3
+```
                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                              Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                              Literate.markdown — Function.
                              Literate.markdown(inputfile, outputdir; kwargs...)
                              Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                              Keyword arguments:
                              • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                              • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                              • codefence: A Pair of opening and closing code fence. Defaults to
                                "```@example $(name)" => "```"
                                if documenter = true and
                                "```julia" => "```"
                                if documenter = false.
                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                              source
                              4.2. Notebook Output
                              The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                              Literate.notebook — Function.
                              Literate.notebook(inputfile, outputdir; kwargs...)
                              Generate a notebook from inputfile and write the result to outputdir.
                              Keyword arguments:
                              • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                              • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                              source
                              4.3. Script Output
                              The (default) script output of the source snippet above is as follows
                              x = 1//3
 
 y = 2//5
 
-z = x + y
                              We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                              Literate.script — Function.
                              Literate.script(inputfile, outputdir; kwargs...)
                              Generate a plain script file from inputfile and write the result to outputdir.
                              Keyword arguments:
                              • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                              • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                              source
                              
+z = x + y

                              We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                              Literate.script — Function.
                              Literate.script(inputfile, outputdir; kwargs...)

                              Generate a plain script file from inputfile and write the result to outputdir.

                              Keyword arguments:

                              • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                              • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                              source
                              \ No newline at end of file diff --git a/v1.0.5/pipeline/index.html b/v1.0.5/pipeline/index.html index 067ff5f..03f7ec6 100644 --- a/v1.0.5/pipeline/index.html +++ b/v1.0.5/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                              3. Processing pipeline

                              3. Processing pipeline

                              The generation of output follows the same pipeline for all output formats:

                              1. Pre-processing
                              2. Parsing
                              3. Document generation
                              4. Post-processing
                              5. Writing to file

                              3.1. Pre-processing

                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                              3.2. Parsing

                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                              # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                              3. Processing pipeline
                              3. Processing pipeline
                              The generation of output follows the same pipeline for all output formats:
                              1. Pre-processing
                              2. Parsing
                              3. Document generation
                              4. Post-processing
                              5. Writing to file
                              3.1. Pre-processing
                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                              3.2. Parsing
                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                              Chunk #2:
                              x = 1 // 3
-y = 2 // 5
                              Chunk #3:
                              When adding `x` and `y` together we obtain a new rational number:
                              Chunk #4:
                              z = x + y
                              It is then up to the Document generation step to decide how these chunks should be treated.
                              Custom control over chunk splits
                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                              x = 1 // 3
+y = 2 // 5
                              Chunk #3:
                              When adding `x` and `y` together we obtain a new rational number:
                              Chunk #4:
                              z = x + y
                              It is then up to the Document generation step to decide how these chunks should be treated.
                              Custom control over chunk splits
                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                              x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                              The example above would result in two consecutive code-chunks.
                              Tip
                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                              3.3. Document generation
                              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, Notebook Output and Script Output. Using the default settings, the following is happening:
                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                              • Script output: markdown chunks are discarded, code chunks are printed as-is.
                              3.4. Post-processing
                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                              3.5. Writing to file
                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                              
+z = x + y

                              The example above would result in two consecutive code-chunks.

                              Tip

                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                              3.3. Document generation

                              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, Notebook Output and Script Output. Using the default settings, the following is happening:

                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                              • Script output: markdown chunks are discarded, code chunks are printed as-is.

                              3.4. Post-processing

                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                              3.5. Writing to file

                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                              \ No newline at end of file diff --git a/v1.0.5/search/index.html b/v1.0.5/search/index.html index 2a66a22..7e10223 100644 --- a/v1.0.5/search/index.html +++ b/v1.0.5/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
                              Search

                              Search

                              Number of results: loading...

                                +Search · Literate.jl
                                Search

                                Search

                                Number of results: loading...

                                  \ No newline at end of file diff --git a/v1.1.0/customprocessing/index.html b/v1.1.0/customprocessing/index.html index 48adc7c..ba1068a 100644 --- a/v1.1.0/customprocessing/index.html +++ b/v1.1.0/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                  5. Custom pre- and post-processing

                                  5. Custom pre- and post-processing

                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                  Example: Adding current date

                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                  # # Example
+5. Custom pre- and post-processing · Literate.jl
                                  5. Custom pre- and post-processing
                                  5. Custom pre- and post-processing
                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                  Example: Adding current date
                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                  # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                  where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                  function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                  Example: Replacing include calls with included code
                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                  # # Replace includes
+end
                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                  Example: Replacing include calls with included code
                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                  # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                  function replace_includes(str)
+include("file2.jl")
                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                  function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                  (of course replace included with your respective files)
                                  Finally, you simply pass this function to e.g. Literate.markdown as
                                  Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                  This approach is used for example in the documentation of the Julia package TimeseriesPrediction, see here and here for the generating script
                                  
+end

                                  (of course replace included with your respective files)

                                  Finally, you simply pass this function to e.g. Literate.markdown as

                                  Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                  This approach is used for example in the documentation of the Julia package TimeseriesPrediction, see here and here for the generating script

                                  \ No newline at end of file diff --git a/v1.1.0/documenter/index.html b/v1.1.0/documenter/index.html index e8b7cb6..452d252 100644 --- a/v1.1.0/documenter/index.html +++ b/v1.1.0/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                  6. Interaction with Documenter.jl

                                  6. Interaction with Documenter.jl

                                  Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                  Literate.markdown:

                                  • The default code fence will change from
                                    ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                    6. Interaction with Documenter.jl
                                    6. Interaction with Documenter.jl
                                    Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                    Literate.markdown:
                                    • The default code fence will change from
                                      ```julia
 # code
 ```
                                      to Documenters @example blocks:
                                      ```@examples $(name)
 # code
-```
                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                      ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                    Literate.notebook:
                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                    • Documenter style markdown math
                                      ```math
+```
                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                      ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                    Literate.notebook:
                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                    • Documenter style markdown math
                                      ```math
 \int f dx
 ```
                                      is replaced with notebook compatible
                                      \begin{equation}
 \int f dx
-\end{equation}
                                    Literate.script:
                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                    
+\end{equation}

                                  Literate.script:

                                  • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                  \ No newline at end of file diff --git a/v1.1.0/fileformat/index.html b/v1.1.0/fileformat/index.html index 1737a43..c9b2186 100644 --- a/v1.1.0/fileformat/index.html +++ b/v1.1.0/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                  2. File Format

                                  2. File Format

                                  The source file format for Literate 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.

                                  2.1. Syntax

                                  The basic syntax is simple:

                                  • lines starting with # are treated as markdown,
                                  • all other lines are treated as julia code.

                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                  Lets look at a simple example:

                                  # # Rational numbers
+2. File Format · Literate.jl
                                  2. File Format
                                  2. File Format
                                  The source file format for Literate 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.
                                  2.1. Syntax
                                  The basic syntax is simple:
                                  • lines starting with # are treated as markdown,
                                  • all other lines are treated as julia code.
                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                  Lets look at a simple example:
                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                  2.2. Filtering Lines
                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                  • #md: line exclusive to markdown output,
                                  • #nb: line exclusive to notebook output,
                                  • #jl: line exclusive to script output,
                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                  Lines starting with one of these tokens are filtered out in the preprocessing step.
                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                  #md # ```@docs
+z = x + y
                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                  2.2. Filtering Lines
                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                  • #md: line exclusive to markdown output,
                                  • #nb: line exclusive to notebook output,
                                  • #jl: line exclusive to script output,
                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                  Lines starting with one of these tokens are filtered out in the preprocessing step.
                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                  #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                  The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                  using Test                      #src
-@test result == expected_result #src
                                  2.3. Default Replacements
                                  The following convenience "macros" are always expanded:
                                  • @__NAME__
                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                  • @__REPO__ROOT_URL__
                                    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
                                  • @__NBVIEWER_ROOT_URL__
                                    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                                  • @__BINDER_ROOT_URL__
                                    expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder)/ where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:
                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__path/to/notebook.inpynb)
                                  
+@test result == expected_result #src

                                  2.3. Default Replacements

                                  The following convenience "macros" are always expanded:

                                  • @__NAME__

                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                  • @__REPO__ROOT_URL__

                                    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

                                  • @__NBVIEWER_ROOT_URL__

                                    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                                  • @__BINDER_ROOT_URL__

                                    expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder)/ where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:

                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__path/to/notebook.inpynb)
                                  \ No newline at end of file diff --git a/v1.1.0/generated/example/index.html b/v1.1.0/generated/example/index.html index f12f77d..c12152a 100644 --- a/v1.1.0/generated/example/index.html +++ b/v1.1.0/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                  7. Example

                                  7. Example

                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                  Basic syntax

                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                  x = 1//3
-y = 2//5
                                  2//5

                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                  • This line starts with #md and is thus only visible in the markdown output.

                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                  x + y
                                  11//15
                                  x * y
                                  2//15

                                  Output Capturing

                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                  function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                  7. Example
                                  7. Example
                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                  Basic syntax
                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                  x = 1//3
+y = 2//5
                                  2//5
                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                  • This line starts with #md and is thus only visible in the markdown output.
                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                  x + y
                                  11//15
                                  x * y
                                  2//15
                                  Output Capturing
                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                  function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                  4-element Array{Int64,1}:
  1
  2
  3
- 4
                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                  using Plots
+ 4
                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                  using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                  
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   2218.28,1038.69 2220.39,1026.23 2222.49,1013.69 2224.59,1001.07 2226.7,988.374 2228.8,975.608 2230.9,962.777 2233,949.885 2235.11,936.937 2237.21,923.937 
   2239.31,910.891 2241.42,897.802 2243.52,884.675 2245.62,871.516 2247.72,858.328 2249.83,845.117 2251.93,831.886 2254.03,818.642 2256.14,805.388 2258.24,792.13 
   
-  "/>
-
   2218.28,134.083 2220.39,129.549 2222.49,125.25 2224.59,121.188 2226.7,117.365 2228.8,113.783 2230.9,110.442 2233,107.343 2235.11,104.489 2237.21,101.879 
   2239.31,99.5152 2241.42,97.3978 2243.52,95.5278 2245.62,93.9057 2247.72,92.5322 2249.83,91.4077 2251.93,90.5327 2254.03,89.9075 2256.14,89.5323 2258.24,89.4072 
   
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                  Custom processing
                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                  z = 1.0 + 2.0im
                                  1.0 + 2.0im
                                  Documenter.jl interaction
                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                  This page was generated using Literate.jl.
                                  
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                  Custom processing
                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                  z = 1.0 + 2.0im
                                  1.0 + 2.0im
                                  Documenter.jl interaction
                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                  This page was generated using Literate.jl.
                                  \ No newline at end of file diff --git a/v1.1.0/index.html b/v1.1.0/index.html index c7f292e..a14efdc 100644 --- a/v1.1.0/index.html +++ b/v1.1.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                  1. Introduction

                                  1. Introduction

                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                  What?

                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                  The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                  Why?

                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                  +1. Introduction · Literate.jl
                                  1. Introduction

                                  1. Introduction

                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                  What?

                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                  The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                  Why?

                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                  \ No newline at end of file diff --git a/v1.1.0/outputformats/index.html b/v1.1.0/outputformats/index.html index 570e247..febce45 100644 --- a/v1.1.0/outputformats/index.html +++ b/v1.1.0/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                  4. Output Formats

                                  4. Output Formats

                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                  # # Rational numbers
+4. Output Formats · Literate.jl
                                  4. Output Formats
                                  4. Output Formats
                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                  and see how this is rendered in each of the output formats.
                                  4.1. Markdown Output
                                  The (default) markdown output of the source snippet above is as follows
                                  ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
                                  and see how this is rendered in each of the output formats.
                                  4.1. Markdown Output
                                  The (default) markdown output of the source snippet above is as follows
                                  ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                  Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                  Literate.markdown — Function.
                                  Literate.markdown(inputfile, outputdir; kwargs...)
                                  Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                  Keyword arguments:
                                  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                  • codefence: A Pair of opening and closing code fence. Defaults to
                                    "```@example $(name)" => "```"
                                    if documenter = true and
                                    "```julia" => "```"
                                    if documenter = false.
                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                  source
                                  4.2. Notebook Output
                                  The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                  Literate.notebook — Function.
                                  Literate.notebook(inputfile, outputdir; kwargs...)
                                  Generate a notebook from inputfile and write the result to outputdir.
                                  Keyword arguments:
                                  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                  source
                                  4.3. Script Output
                                  The (default) script output of the source snippet above is as follows
                                  x = 1//3
+```
                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                  Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                  Literate.markdown — Function.
                                  Literate.markdown(inputfile, outputdir; kwargs...)
                                  Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                  Keyword arguments:
                                  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                  • codefence: A Pair of opening and closing code fence. Defaults to
                                    "```@example $(name)" => "```"
                                    if documenter = true and
                                    "```julia" => "```"
                                    if documenter = false.
                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                  source
                                  4.2. Notebook Output
                                  The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                  Literate.notebook — Function.
                                  Literate.notebook(inputfile, outputdir; kwargs...)
                                  Generate a notebook from inputfile and write the result to outputdir.
                                  Keyword arguments:
                                  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                  source
                                  4.3. Script Output
                                  The (default) script output of the source snippet above is as follows
                                  x = 1//3
 
 y = 2//5
 
-z = x + y
                                  We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                                  Literate.script — Function.
                                  Literate.script(inputfile, outputdir; kwargs...)
                                  Generate a plain script file from inputfile and write the result to outputdir.
                                  Keyword arguments:
                                  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                  source
                                  
+z = x + y

                                  We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                                  Literate.script — Function.
                                  Literate.script(inputfile, outputdir; kwargs...)

                                  Generate a plain script file from inputfile and write the result to outputdir.

                                  Keyword arguments:

                                  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                  source
                                  \ No newline at end of file diff --git a/v1.1.0/pipeline/index.html b/v1.1.0/pipeline/index.html index 067ff5f..03f7ec6 100644 --- a/v1.1.0/pipeline/index.html +++ b/v1.1.0/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                  3. Processing pipeline

                                  3. Processing pipeline

                                  The generation of output follows the same pipeline for all output formats:

                                  1. Pre-processing
                                  2. Parsing
                                  3. Document generation
                                  4. Post-processing
                                  5. Writing to file

                                  3.1. Pre-processing

                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                  3.2. Parsing

                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                  # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                  3. Processing pipeline
                                  3. Processing pipeline
                                  The generation of output follows the same pipeline for all output formats:
                                  1. Pre-processing
                                  2. Parsing
                                  3. Document generation
                                  4. Post-processing
                                  5. Writing to file
                                  3.1. Pre-processing
                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                  3.2. Parsing
                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                  Chunk #2:
                                  x = 1 // 3
-y = 2 // 5
                                  Chunk #3:
                                  When adding `x` and `y` together we obtain a new rational number:
                                  Chunk #4:
                                  z = x + y
                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                  Custom control over chunk splits
                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                  x = 1 // 3
+y = 2 // 5
                                  Chunk #3:
                                  When adding `x` and `y` together we obtain a new rational number:
                                  Chunk #4:
                                  z = x + y
                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                  Custom control over chunk splits
                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                  x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                  The example above would result in two consecutive code-chunks.
                                  Tip
                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                  3.3. Document generation
                                  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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                  3.4. Post-processing
                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                  3.5. Writing to file
                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                  
+z = x + y

                                  The example above would result in two consecutive code-chunks.

                                  Tip

                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                  3.3. Document generation

                                  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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                  3.4. Post-processing

                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                  3.5. Writing to file

                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                  \ No newline at end of file diff --git a/v1.1.0/search/index.html b/v1.1.0/search/index.html index 2a66a22..7e10223 100644 --- a/v1.1.0/search/index.html +++ b/v1.1.0/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
                                  Search

                                  Search

                                  Number of results: loading...

                                    +Search · Literate.jl
                                    Search

                                    Search

                                    Number of results: loading...

                                      \ No newline at end of file diff --git a/v2.0.0/customprocessing/index.html b/v2.0.0/customprocessing/index.html index c042d88..edfc29a 100644 --- a/v2.0.0/customprocessing/index.html +++ b/v2.0.0/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                      5. Custom pre- and post-processing

                                      5. Custom pre- and post-processing

                                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                      Example: Adding current date

                                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                      # # Example
+5. Custom pre- and post-processing · Literate.jl
                                      5. Custom pre- and post-processing
                                      5. Custom pre- and post-processing
                                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                      Example: Adding current date
                                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                      # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                      where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                      function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                      Example: Replacing include calls with included code
                                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                      # # Replace includes
+end
                                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                      Example: Replacing include calls with included code
                                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                      # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                      function replace_includes(str)
+include("file2.jl")
                                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                      function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                      (of course replace included with your respective files)
                                      Finally, you simply pass this function to e.g. Literate.markdown as
                                      Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                      This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                      
+end

                                      (of course replace included with your respective files)

                                      Finally, you simply pass this function to e.g. Literate.markdown as

                                      Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                      This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                      \ No newline at end of file diff --git a/v2.0.0/documenter/index.html b/v2.0.0/documenter/index.html index 5616e90..a5fa46a 100644 --- a/v2.0.0/documenter/index.html +++ b/v2.0.0/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                      6. Interaction with Documenter.jl

                                      6. Interaction with Documenter.jl

                                      Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                      Literate.markdown:

                                      • The default code fence will change from
                                        ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                        6. Interaction with Documenter.jl
                                        6. Interaction with Documenter.jl
                                        Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                        Literate.markdown:
                                        • The default code fence will change from
                                          ```julia
 # code
 ```
                                          to Documenters @example blocks:
                                          ```@examples $(name)
 # code
-```
                                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                          ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                        Literate.notebook:
                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                        • Documenter style markdown math
                                          ```math
+```
                                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                          ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                        Literate.notebook:
                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                        • Documenter style markdown math
                                          ```math
 \int f dx
 ```
                                          is replaced with notebook compatible
                                          \begin{equation}
 \int f dx
-\end{equation}
                                        Literate.script:
                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                        
+\end{equation}

                                      Literate.script:

                                      • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                      \ No newline at end of file diff --git a/v2.0.0/fileformat/index.html b/v2.0.0/fileformat/index.html index 26e071a..3fe5af7 100644 --- a/v2.0.0/fileformat/index.html +++ b/v2.0.0/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                      2. File Format

                                      2. File Format

                                      The source file format for Literate 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.

                                      2.1. Syntax

                                      The basic syntax is simple:

                                      • lines starting with # are treated as markdown,
                                      • all other lines are treated as julia code.

                                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                      Lets look at a simple example:

                                      # # Rational numbers
+2. File Format · Literate.jl
                                      2. File Format
                                      2. File Format
                                      The source file format for Literate 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.
                                      2.1. Syntax
                                      The basic syntax is simple:
                                      • lines starting with # are treated as markdown,
                                      • all other lines are treated as julia code.
                                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                      Lets look at a simple example:
                                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -9,9 +50,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                      For simple use this is all you need to know. The following additional special syntax can also be used:
                                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                                      2.2. Filtering Lines
                                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                      • #md: line exclusive to markdown output,
                                      • #nb: line exclusive to notebook output,
                                      • #jl: line exclusive to script output,
                                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                                      Lines starting with one of these tokens are filtered out in the preprocessing step.
                                      Tip
                                      The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                                      #md # ```@docs
+z = x + y
                                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                      For simple use this is all you need to know. The following additional special syntax can also be used:
                                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                                      2.2. Filtering Lines
                                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                      • #md: line exclusive to markdown output,
                                      • #nb: line exclusive to notebook output,
                                      • #jl: line exclusive to script output,
                                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                                      Lines starting with one of these tokens are filtered out in the preprocessing step.
                                      Tip
                                      The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                                      #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                      The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                      using Test                      #src
-@test result == expected_result #src
                                      2.3. Default Replacements
                                      The following convenience "macros" are always expanded:
                                      • @__NAME__
                                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                      • @__REPO__ROOT_URL__
                                        expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.
                                      • @__NBVIEWER_ROOT_URL__
                                        expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                                      • @__BINDER_ROOT_URL__
                                        expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder)/ where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:
                                        [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__path/to/notebook.inpynb)
                                      
+@test result == expected_result #src

                                      2.3. Default Replacements

                                      The following convenience "macros" are always expanded:

                                      • @__NAME__

                                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                      • @__REPO__ROOT_URL__

                                        expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

                                      • @__NBVIEWER_ROOT_URL__

                                        expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                                      • @__BINDER_ROOT_URL__

                                        expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder)/ where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:

                                        [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__path/to/notebook.inpynb)
                                      \ No newline at end of file diff --git a/v2.0.0/generated/example/index.html b/v2.0.0/generated/example/index.html index 54ee4b1..714a3fc 100644 --- a/v2.0.0/generated/example/index.html +++ b/v2.0.0/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                      7. Example

                                      7. Example

                                      This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                      Basic syntax

                                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                      x = 1//3
-y = 2//5
                                      2//5

                                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                      • This line starts with #md and is thus only visible in the markdown output.

                                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                      x + y
                                      11//15
                                      x * y
                                      2//15

                                      Output Capturing

                                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                      Note

                                      Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                      function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                      7. Example
                                      7. Example
                                      This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                      Basic syntax
                                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                      x = 1//3
+y = 2//5
                                      2//5
                                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                      • This line starts with #md and is thus only visible in the markdown output.
                                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                      x + y
                                      11//15
                                      x * y
                                      2//15
                                      Output Capturing
                                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                      Note
                                      Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                      function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                      4-element Array{Int64,1}:
  1
  2
  3
- 4
                                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                      using Plots
+ 4
                                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                      using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                      
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   2247.98,1028.05 2250.12,1015.72 2252.26,1003.31 2254.4,990.826 2256.54,978.267 2258.68,965.638 2260.82,952.944 2262.95,940.191 2265.09,927.382 2267.23,914.522
   2269.37,901.615 2271.51,888.667 2273.65,875.681 2275.79,862.663 2277.93,849.617 2280.07,836.548 2282.21,823.459 2284.35,810.357 2286.49,797.246 2288.63,784.13
 
-  "/>
-
   2247.98,133.151 2250.12,128.665 2252.26,124.412 2254.4,120.394 2256.54,116.612 2258.68,113.068 2260.82,109.763 2262.95,106.698 2265.09,103.874 2267.23,101.292
   2269.37,98.9539 2271.51,96.8592 2273.65,95.0092 2275.79,93.4045 2277.93,92.0458 2280.07,90.9334 2282.21,90.0678 2284.35,89.4493 2286.49,89.0781 2288.63,88.9544
 
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                      Custom processing
                                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                      z = 1.0 + 2.0im
                                      1.0 + 2.0im
                                      Documenter.jl interaction
                                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                      This page was generated using Literate.jl.
                                      
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                      Custom processing
                                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                      z = 1.0 + 2.0im
                                      1.0 + 2.0im
                                      Documenter.jl interaction
                                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                      This page was generated using Literate.jl.
                                      \ No newline at end of file diff --git a/v2.0.0/generated/name/index.html b/v2.0.0/generated/name/index.html index 2bd4ddf..cad3560 100644 --- a/v2.0.0/generated/name/index.html +++ b/v2.0.0/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                      Rational numbers

                                      Rational numbers

                                      In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                      x = 1//3
                                      1//3
                                      y = 2//5
                                      2//5

                                      When adding x and y together we obtain a new rational number:

                                      z = x + y
                                      11//15
                                      +Rational numbers · Literate.jl
                                      Rational numbers

                                      Rational numbers

                                      In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                      x = 1//3
                                      1//3
                                      y = 2//5
                                      2//5

                                      When adding x and y together we obtain a new rational number:

                                      z = x + y
                                      11//15
                                      \ No newline at end of file diff --git a/v2.0.0/index.html b/v2.0.0/index.html index 7eb9e3c..0e4267f 100644 --- a/v2.0.0/index.html +++ b/v2.0.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                      1. Introduction

                                      1. Introduction

                                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                      What?

                                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                      Why?

                                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                      It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                      +1. Introduction · Literate.jl
                                      1. Introduction

                                      1. Introduction

                                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                      What?

                                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                      Why?

                                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                      It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                      \ No newline at end of file diff --git a/v2.0.0/outputformats/index.html b/v2.0.0/outputformats/index.html index b65de7e..c48c001 100644 --- a/v2.0.0/outputformats/index.html +++ b/v2.0.0/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                      4. Output Formats

                                      4. Output Formats

                                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                      # # Rational numbers
+4. Output Formats · Literate.jl
                                      4. Output Formats
                                      4. Output Formats
                                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                      and see how this is rendered in each of the output formats.
                                      4.1. Markdown Output
                                      The (default) markdown output of the source snippet above is as follows
                                      ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
                                      and see how this is rendered in each of the output formats.
                                      4.1. Markdown Output
                                      The (default) markdown output of the source snippet above is as follows
                                      ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                      Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                      Literate.markdown — Function.
                                      Literate.markdown(inputfile, outputdir; kwargs...)
                                      Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                      Keyword arguments:
                                      • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                      • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                      • codefence: A Pair of opening and closing code fence. Defaults to
                                        "```@example $(name)" => "```"
                                        if documenter = true and
                                        "```julia" => "```"
                                        if documenter = false.
                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                      source
                                      4.2. Notebook Output
                                      The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                      Literate.notebook — Function.
                                      Literate.notebook(inputfile, outputdir; kwargs...)
                                      Generate a notebook from inputfile and write the result to outputdir.
                                      Keyword arguments:
                                      • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                      • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                      source
                                      Notebook metadata
                                      Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                      %% optional ignored text [type] {optional metadata JSON}
                                      Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                      4.3. Script Output
                                      The (default) script output of the source snippet above is as follows
                                      x = 1//3
+```
                                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                      Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                      Literate.markdown — Function.
                                      Literate.markdown(inputfile, outputdir; kwargs...)
                                      Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                      Keyword arguments:
                                      • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                      • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                      • codefence: A Pair of opening and closing code fence. Defaults to
                                        "```@example $(name)" => "```"
                                        if documenter = true and
                                        "```julia" => "```"
                                        if documenter = false.
                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                      source
                                      4.2. Notebook Output
                                      The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                      Literate.notebook — Function.
                                      Literate.notebook(inputfile, outputdir; kwargs...)
                                      Generate a notebook from inputfile and write the result to outputdir.
                                      Keyword arguments:
                                      • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                      • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                      source
                                      Notebook metadata
                                      Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                      %% optional ignored text [type] {optional metadata JSON}
                                      Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                      4.3. Script Output
                                      The (default) script output of the source snippet above is as follows
                                      x = 1//3
 
 y = 2//5
 
-z = x + y
                                      We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                                      Literate.script — Function.
                                      Literate.script(inputfile, outputdir; kwargs...)
                                      Generate a plain script file from inputfile and write the result to outputdir.
                                      Keyword arguments:
                                      • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                      • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                      source
                                      
+z = x + y

                                      We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                                      Literate.script — Function.
                                      Literate.script(inputfile, outputdir; kwargs...)

                                      Generate a plain script file from inputfile and write the result to outputdir.

                                      Keyword arguments:

                                      • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                      • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                      source
                                      \ No newline at end of file diff --git a/v2.0.0/pipeline/index.html b/v2.0.0/pipeline/index.html index c4a016d..b0c7a61 100644 --- a/v2.0.0/pipeline/index.html +++ b/v2.0.0/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                      3. Processing pipeline

                                      3. Processing pipeline

                                      The generation of output follows the same pipeline for all output formats:

                                      1. Pre-processing
                                      2. Parsing
                                      3. Document generation
                                      4. Post-processing
                                      5. Writing to file

                                      3.1. Pre-processing

                                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                      3.2. Parsing

                                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                      # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                      3. Processing pipeline
                                      3. Processing pipeline
                                      The generation of output follows the same pipeline for all output formats:
                                      1. Pre-processing
                                      2. Parsing
                                      3. Document generation
                                      4. Post-processing
                                      5. Writing to file
                                      3.1. Pre-processing
                                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                      3.2. Parsing
                                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -9,7 +50,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -23,7 +64,7 @@ z = x + y                                                                ┘ cod
 
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                      Chunk #2:
                                      x = 1 // 3
-y = 2 // 5
                                      Chunk #3:
                                      When adding `x` and `y` together we obtain a new rational number:
                                      Chunk #4:
                                      z = x + y
                                      It is then up to the Document generation step to decide how these chunks should be treated.
                                      Custom control over chunk splits
                                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                      x = 1 // 3
+y = 2 // 5
                                      Chunk #3:
                                      When adding `x` and `y` together we obtain a new rational number:
                                      Chunk #4:
                                      z = x + y
                                      It is then up to the Document generation step to decide how these chunks should be treated.
                                      Custom control over chunk splits
                                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                      x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                      The example above would result in two consecutive code-chunks.
                                      Tip
                                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                      It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                      3.3. Document generation
                                      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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                      • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                      3.4. Post-processing
                                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                      3.5. Writing to file
                                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                      
+z = x + y

                                      The example above would result in two consecutive code-chunks.

                                      Tip

                                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                      It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                      3.3. Document generation

                                      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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                      • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                      3.4. Post-processing

                                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                      3.5. Writing to file

                                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                      \ No newline at end of file diff --git a/v2.0.0/search/index.html b/v2.0.0/search/index.html index c9635ef..7b689b4 100644 --- a/v2.0.0/search/index.html +++ b/v2.0.0/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
                                      Search

                                      Search

                                      Number of results: loading...

                                        +Search · Literate.jl
                                        Search

                                        Search

                                        Number of results: loading...

                                          \ No newline at end of file diff --git a/v2.0.2/customprocessing/index.html b/v2.0.2/customprocessing/index.html index c042d88..edfc29a 100644 --- a/v2.0.2/customprocessing/index.html +++ b/v2.0.2/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                          5. Custom pre- and post-processing

                                          5. Custom pre- and post-processing

                                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                          Example: Adding current date

                                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                          # # Example
+5. Custom pre- and post-processing · Literate.jl
                                          5. Custom pre- and post-processing
                                          5. Custom pre- and post-processing
                                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                          Example: Adding current date
                                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                          # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                          where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                          function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                          Example: Replacing include calls with included code
                                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                          # # Replace includes
+end
                                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                          Example: Replacing include calls with included code
                                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                          # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                          function replace_includes(str)
+include("file2.jl")
                                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                          function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                          (of course replace included with your respective files)
                                          Finally, you simply pass this function to e.g. Literate.markdown as
                                          Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                          This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                          
+end

                                          (of course replace included with your respective files)

                                          Finally, you simply pass this function to e.g. Literate.markdown as

                                          Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                          This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                          \ No newline at end of file diff --git a/v2.0.2/documenter/index.html b/v2.0.2/documenter/index.html index 5616e90..a5fa46a 100644 --- a/v2.0.2/documenter/index.html +++ b/v2.0.2/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                          6. Interaction with Documenter.jl

                                          6. Interaction with Documenter.jl

                                          Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                          Literate.markdown:

                                          • The default code fence will change from
                                            ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                            6. Interaction with Documenter.jl
                                            6. Interaction with Documenter.jl
                                            Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                            Literate.markdown:
                                            • The default code fence will change from
                                              ```julia
 # code
 ```
                                              to Documenters @example blocks:
                                              ```@examples $(name)
 # code
-```
                                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                              ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                            Literate.notebook:
                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                            • Documenter style markdown math
                                              ```math
+```
                                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                              ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                            Literate.notebook:
                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                            • Documenter style markdown math
                                              ```math
 \int f dx
 ```
                                              is replaced with notebook compatible
                                              \begin{equation}
 \int f dx
-\end{equation}
                                            Literate.script:
                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                            
+\end{equation}

                                          Literate.script:

                                          • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                          \ No newline at end of file diff --git a/v2.0.2/fileformat/index.html b/v2.0.2/fileformat/index.html index effedf6..e3d434f 100644 --- a/v2.0.2/fileformat/index.html +++ b/v2.0.2/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                          2. File Format

                                          2. File Format

                                          The source file format for Literate 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.

                                          2.1. Syntax

                                          The basic syntax is simple:

                                          • lines starting with # are treated as markdown,
                                          • all other lines are treated as julia code.

                                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                          Lets look at a simple example:

                                          # # Rational numbers
+2. File Format · Literate.jl
                                          2. File Format
                                          2. File Format
                                          The source file format for Literate 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.
                                          2.1. Syntax
                                          The basic syntax is simple:
                                          • lines starting with # are treated as markdown,
                                          • all other lines are treated as julia code.
                                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                          Lets look at a simple example:
                                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                          For simple use this is all you need to know. The following additional special syntax can also be used:
                                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                                          2.2. Filtering Lines
                                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                          • #md: line exclusive to markdown output,
                                          • #nb: line exclusive to notebook output,
                                          • #jl: line exclusive to script output,
                                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                                          Lines starting with one of these tokens are filtered out in the preprocessing step.
                                          Tip
                                          The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                                          #md # ```@docs
+z = x + y
                                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                          For simple use this is all you need to know. The following additional special syntax can also be used:
                                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                                          2.2. Filtering Lines
                                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                          • #md: line exclusive to markdown output,
                                          • #nb: line exclusive to notebook output,
                                          • #jl: line exclusive to script output,
                                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                                          Lines starting with one of these tokens are filtered out in the preprocessing step.
                                          Tip
                                          The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                                          #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                          The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                          using Test                      #src
-@test result == expected_result #src
                                          2.3. Default Replacements
                                          The following convenience "macros" are always expanded:
                                          • @__NAME__
                                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                          • @__REPO_ROOT_URL__
                                            expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.
                                          • @__NBVIEWER_ROOT_URL__
                                            expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                                          • @__BINDER_ROOT_URL__
                                            expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:
                                            [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                          Note
                                          @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.
                                          
+@test result == expected_result #src

                                          2.3. Default Replacements

                                          The following convenience "macros" are always expanded:

                                          • @__NAME__

                                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                          • @__REPO_ROOT_URL__

                                            expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.

                                          • @__NBVIEWER_ROOT_URL__

                                            expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                                          • @__BINDER_ROOT_URL__

                                            expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:

                                            [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                          Note

                                          @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.

                                          \ No newline at end of file diff --git a/v2.0.2/generated/example/index.html b/v2.0.2/generated/example/index.html index 908f42f..435383d 100644 --- a/v2.0.2/generated/example/index.html +++ b/v2.0.2/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                          7. Example

                                          7. Example

                                          This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                          Basic syntax

                                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                          x = 1//3
-y = 2//5
                                          2//5

                                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                          • This line starts with #md and is thus only visible in the markdown output.

                                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                          x + y
                                          11//15
                                          x * y
                                          2//15

                                          Output Capturing

                                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                          Note

                                          Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                          function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                          7. Example
                                          7. Example
                                          This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                          Basic syntax
                                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                          x = 1//3
+y = 2//5
                                          2//5
                                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                          • This line starts with #md and is thus only visible in the markdown output.
                                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                          x + y
                                          11//15
                                          x * y
                                          2//15
                                          Output Capturing
                                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                          Note
                                          Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                          function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                          4-element Array{Int64,1}:
  1
  2
  3
- 4
                                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                          using Plots
+ 4
                                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                          using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                          
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   2247.98,1028.05 2250.12,1015.72 2252.26,1003.31 2254.4,990.826 2256.54,978.267 2258.68,965.638 2260.82,952.944 2262.95,940.191 2265.09,927.382 2267.23,914.522
   2269.37,901.615 2271.51,888.667 2273.65,875.681 2275.79,862.663 2277.93,849.617 2280.07,836.548 2282.21,823.459 2284.35,810.357 2286.49,797.246 2288.63,784.13
 
-  "/>
-
   2247.98,133.151 2250.12,128.665 2252.26,124.412 2254.4,120.394 2256.54,116.612 2258.68,113.068 2260.82,109.763 2262.95,106.698 2265.09,103.874 2267.23,101.292
   2269.37,98.9539 2271.51,96.8592 2273.65,95.0092 2275.79,93.4045 2277.93,92.0458 2280.07,90.9334 2282.21,90.0678 2284.35,89.4493 2286.49,89.0781 2288.63,88.9544
 
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                          Custom processing
                                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                          z = 1.0 + 2.0im
                                          1.0 + 2.0im
                                          Documenter.jl interaction
                                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                          This page was generated using Literate.jl.
                                          
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                          Custom processing
                                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                          z = 1.0 + 2.0im
                                          1.0 + 2.0im
                                          Documenter.jl interaction
                                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                          This page was generated using Literate.jl.
                                          \ No newline at end of file diff --git a/v2.0.2/generated/name/index.html b/v2.0.2/generated/name/index.html index 2bd4ddf..cad3560 100644 --- a/v2.0.2/generated/name/index.html +++ b/v2.0.2/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                          Rational numbers

                                          Rational numbers

                                          In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                          x = 1//3
                                          1//3
                                          y = 2//5
                                          2//5

                                          When adding x and y together we obtain a new rational number:

                                          z = x + y
                                          11//15
                                          +Rational numbers · Literate.jl
                                          Rational numbers

                                          Rational numbers

                                          In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                          x = 1//3
                                          1//3
                                          y = 2//5
                                          2//5

                                          When adding x and y together we obtain a new rational number:

                                          z = x + y
                                          11//15
                                          \ No newline at end of file diff --git a/v2.0.2/index.html b/v2.0.2/index.html index 7eb9e3c..0e4267f 100644 --- a/v2.0.2/index.html +++ b/v2.0.2/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                          1. Introduction

                                          1. Introduction

                                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                          What?

                                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                          Why?

                                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                          It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                          +1. Introduction · Literate.jl
                                          1. Introduction

                                          1. Introduction

                                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                          What?

                                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                          Why?

                                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                          It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                          \ No newline at end of file diff --git a/v2.0.2/outputformats/index.html b/v2.0.2/outputformats/index.html index 6dd6fa7..03d46f7 100644 --- a/v2.0.2/outputformats/index.html +++ b/v2.0.2/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                          4. Output Formats

                                          4. Output Formats

                                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                          # # Rational numbers
+4. Output Formats · Literate.jl
                                          4. Output Formats
                                          4. Output Formats
                                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                          and see how this is rendered in each of the output formats.
                                          4.1. Markdown Output
                                          The (default) markdown output of the source snippet above is as follows
                                          ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
                                          and see how this is rendered in each of the output formats.
                                          4.1. Markdown Output
                                          The (default) markdown output of the source snippet above is as follows
                                          ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                          Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                          Literate.markdown — Function.
                                          Literate.markdown(inputfile, outputdir; kwargs...)
                                          Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                          Keyword arguments:
                                          • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                          • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                          • codefence: A Pair of opening and closing code fence. Defaults to
                                            "```@example $(name)" => "```"
                                            if documenter = true and
                                            "```julia" => "```"
                                            if documenter = false.
                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                          source
                                          4.2. Notebook Output
                                          The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                          Literate.notebook — Function.
                                          Literate.notebook(inputfile, outputdir; kwargs...)
                                          Generate a notebook from inputfile and write the result to outputdir.
                                          Keyword arguments:
                                          • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                          • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                          source
                                          Notebook metadata
                                          Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                          %% optional ignored text [type] {optional metadata JSON}
                                          Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                          4.3. Script Output
                                          The (default) script output of the source snippet above is as follows
                                          x = 1//3
+```
                                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                          Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                          Literate.markdown — Function.
                                          Literate.markdown(inputfile, outputdir; kwargs...)
                                          Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                          Keyword arguments:
                                          • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                          • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                          • codefence: A Pair of opening and closing code fence. Defaults to
                                            "```@example $(name)" => "```"
                                            if documenter = true and
                                            "```julia" => "```"
                                            if documenter = false.
                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                          source
                                          4.2. Notebook Output
                                          The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                          Literate.notebook — Function.
                                          Literate.notebook(inputfile, outputdir; kwargs...)
                                          Generate a notebook from inputfile and write the result to outputdir.
                                          Keyword arguments:
                                          • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                          • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                          source
                                          Notebook metadata
                                          Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                          %% optional ignored text [type] {optional metadata JSON}
                                          Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                          4.3. Script Output
                                          The (default) script output of the source snippet above is as follows
                                          x = 1//3
 
 y = 2//5
 
-z = x + y
                                          We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                                          Literate.script — Function.
                                          Literate.script(inputfile, outputdir; kwargs...)
                                          Generate a plain script file from inputfile and write the result to outputdir.
                                          Keyword arguments:
                                          • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                          • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                          source
                                          
+z = x + y

                                          We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                                          Literate.script — Function.
                                          Literate.script(inputfile, outputdir; kwargs...)

                                          Generate a plain script file from inputfile and write the result to outputdir.

                                          Keyword arguments:

                                          • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                          • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                          source
                                          \ No newline at end of file diff --git a/v2.0.2/pipeline/index.html b/v2.0.2/pipeline/index.html index 2712f81..ee291b8 100644 --- a/v2.0.2/pipeline/index.html +++ b/v2.0.2/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                          3. Processing pipeline

                                          3. Processing pipeline

                                          The generation of output follows the same pipeline for all output formats:

                                          1. Pre-processing
                                          2. Parsing
                                          3. Document generation
                                          4. Post-processing
                                          5. Writing to file

                                          3.1. Pre-processing

                                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                          3.2. Parsing

                                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                          # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                          3. Processing pipeline
                                          3. Processing pipeline
                                          The generation of output follows the same pipeline for all output formats:
                                          1. Pre-processing
                                          2. Parsing
                                          3. Document generation
                                          4. Post-processing
                                          5. Writing to file
                                          3.1. Pre-processing
                                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                          3.2. Parsing
                                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                          Chunk #2:
                                          # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                          Chunk #3:
                                          When adding `x` and `y` together we obtain a new rational number:
                                          Chunk #4:
                                          z = x + y
                                          It is then up to the Document generation step to decide how these chunks should be treated.
                                          Custom control over chunk splits
                                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                          x = 1 // 3
+y = 2 // 5
                                          Chunk #3:
                                          When adding `x` and `y` together we obtain a new rational number:
                                          Chunk #4:
                                          z = x + y
                                          It is then up to the Document generation step to decide how these chunks should be treated.
                                          Custom control over chunk splits
                                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                          x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                          The example above would result in two consecutive code-chunks.
                                          Tip
                                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                          It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                          3.3. Document generation
                                          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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                          • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                          3.4. Post-processing
                                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                          3.5. Writing to file
                                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                          
+z = x + y

                                          The example above would result in two consecutive code-chunks.

                                          Tip

                                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                          It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                          3.3. Document generation

                                          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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                          • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                          3.4. Post-processing

                                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                          3.5. Writing to file

                                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                          \ No newline at end of file diff --git a/v2.0.2/search/index.html b/v2.0.2/search/index.html index c9635ef..7b689b4 100644 --- a/v2.0.2/search/index.html +++ b/v2.0.2/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
                                          Search

                                          Search

                                          Number of results: loading...

                                            +Search · Literate.jl
                                            Search

                                            Search

                                            Number of results: loading...

                                              \ No newline at end of file diff --git a/v2.0.3/customprocessing/index.html b/v2.0.3/customprocessing/index.html index c042d88..edfc29a 100644 --- a/v2.0.3/customprocessing/index.html +++ b/v2.0.3/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                              5. Custom pre- and post-processing

                                              5. Custom pre- and post-processing

                                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                              Example: Adding current date

                                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                              # # Example
+5. Custom pre- and post-processing · Literate.jl
                                              5. Custom pre- and post-processing
                                              5. Custom pre- and post-processing
                                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                              Example: Adding current date
                                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                              # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                              where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                              function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                              Example: Replacing include calls with included code
                                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                              # # Replace includes
+end
                                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                              Example: Replacing include calls with included code
                                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                              # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                              function replace_includes(str)
+include("file2.jl")
                                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                              function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                              (of course replace included with your respective files)
                                              Finally, you simply pass this function to e.g. Literate.markdown as
                                              Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                              This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                              
+end

                                              (of course replace included with your respective files)

                                              Finally, you simply pass this function to e.g. Literate.markdown as

                                              Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                              This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                              \ No newline at end of file diff --git a/v2.0.3/documenter/index.html b/v2.0.3/documenter/index.html index 4dd45f7..caf5e65 100644 --- a/v2.0.3/documenter/index.html +++ b/v2.0.3/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                              6. Interaction with Documenter.jl

                                              6. Interaction with Documenter.jl

                                              Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                              Literate.markdown:

                                              • The default code fence will change from
                                                ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                6. Interaction with Documenter.jl
                                                6. Interaction with Documenter.jl
                                                Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                Literate.markdown:
                                                • The default code fence will change from
                                                  ```julia
 # code
 ```
                                                  to Documenters @example blocks:
                                                  ```@examples $(name)
 # code
-```
                                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                  ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                Literate.notebook:
                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                • Documenter style markdown math
                                                  ```math
+```
                                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                  ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                Literate.notebook:
                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                • Documenter style markdown math
                                                  ```math
 \int f dx
 ```
                                                  is replaced with notebook compatible
                                                  $$
 \int f dx
-$$
                                                Literate.script:
                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                
+$$

                                              Literate.script:

                                              • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                              \ No newline at end of file diff --git a/v2.0.3/fileformat/index.html b/v2.0.3/fileformat/index.html index effedf6..e3d434f 100644 --- a/v2.0.3/fileformat/index.html +++ b/v2.0.3/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                              2. File Format

                                              2. File Format

                                              The source file format for Literate 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.

                                              2.1. Syntax

                                              The basic syntax is simple:

                                              • lines starting with # are treated as markdown,
                                              • all other lines are treated as julia code.

                                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                              Lets look at a simple example:

                                              # # Rational numbers
+2. File Format · Literate.jl
                                              2. File Format
                                              2. File Format
                                              The source file format for Literate 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.
                                              2.1. Syntax
                                              The basic syntax is simple:
                                              • lines starting with # are treated as markdown,
                                              • all other lines are treated as julia code.
                                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                              Lets look at a simple example:
                                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                              For simple use this is all you need to know. The following additional special syntax can also be used:
                                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                                              2.2. Filtering Lines
                                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                              • #md: line exclusive to markdown output,
                                              • #nb: line exclusive to notebook output,
                                              • #jl: line exclusive to script output,
                                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                                              Lines starting with one of these tokens are filtered out in the preprocessing step.
                                              Tip
                                              The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                                              #md # ```@docs
+z = x + y
                                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                              For simple use this is all you need to know. The following additional special syntax can also be used:
                                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                                              2.2. Filtering Lines
                                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                              • #md: line exclusive to markdown output,
                                              • #nb: line exclusive to notebook output,
                                              • #jl: line exclusive to script output,
                                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                                              Lines starting with one of these tokens are filtered out in the preprocessing step.
                                              Tip
                                              The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                                              #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                              The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                              using Test                      #src
-@test result == expected_result #src
                                              2.3. Default Replacements
                                              The following convenience "macros" are always expanded:
                                              • @__NAME__
                                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                              • @__REPO_ROOT_URL__
                                                expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.
                                              • @__NBVIEWER_ROOT_URL__
                                                expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                                              • @__BINDER_ROOT_URL__
                                                expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:
                                                [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                              Note
                                              @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.
                                              
+@test result == expected_result #src

                                              2.3. Default Replacements

                                              The following convenience "macros" are always expanded:

                                              • @__NAME__

                                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                              • @__REPO_ROOT_URL__

                                                expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.

                                              • @__NBVIEWER_ROOT_URL__

                                                expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                                              • @__BINDER_ROOT_URL__

                                                expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:

                                                [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                              Note

                                              @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.

                                              \ No newline at end of file diff --git a/v2.0.3/generated/example/index.html b/v2.0.3/generated/example/index.html index eb97c46..3dc582e 100644 --- a/v2.0.3/generated/example/index.html +++ b/v2.0.3/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                              7. Example

                                              7. Example

                                              This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                              Basic syntax

                                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                              x = 1//3
-y = 2//5
                                              2//5

                                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                              • This line starts with #md and is thus only visible in the markdown output.

                                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                              x + y
                                              11//15
                                              x * y
                                              2//15

                                              Output Capturing

                                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                              Note

                                              Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                              function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                              7. Example
                                              7. Example
                                              This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                              Basic syntax
                                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                              x = 1//3
+y = 2//5
                                              2//5
                                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                              • This line starts with #md and is thus only visible in the markdown output.
                                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                              x + y
                                              11//15
                                              x * y
                                              2//15
                                              Output Capturing
                                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                              Note
                                              Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                              function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                              4-element Array{Int64,1}:
  1
  2
  3
- 4
                                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                              using Plots
+ 4
                                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                              using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                              
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   2247.98,1028.05 2250.12,1015.72 2252.26,1003.31 2254.4,990.826 2256.54,978.267 2258.68,965.638 2260.82,952.944 2262.95,940.191 2265.09,927.382 2267.23,914.522
   2269.37,901.615 2271.51,888.667 2273.65,875.681 2275.79,862.663 2277.93,849.617 2280.07,836.548 2282.21,823.459 2284.35,810.357 2286.49,797.246 2288.63,784.13
 
-  "/>
-
   2247.98,133.151 2250.12,128.665 2252.26,124.412 2254.4,120.394 2256.54,116.612 2258.68,113.068 2260.82,109.763 2262.95,106.698 2265.09,103.874 2267.23,101.292
   2269.37,98.9539 2271.51,96.8592 2273.65,95.0092 2275.79,93.4045 2277.93,92.0458 2280.07,90.9334 2282.21,90.0678 2284.35,89.4493 2286.49,89.0781 2288.63,88.9544
 
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                              Custom processing
                                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                              z = 1.0 + 2.0im
                                              1.0 + 2.0im
                                              Documenter.jl interaction
                                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                              This page was generated using Literate.jl.
                                              
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                              Custom processing
                                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                              z = 1.0 + 2.0im
                                              1.0 + 2.0im
                                              Documenter.jl interaction
                                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                              This page was generated using Literate.jl.
                                              \ No newline at end of file diff --git a/v2.0.3/generated/name/index.html b/v2.0.3/generated/name/index.html index 2bd4ddf..cad3560 100644 --- a/v2.0.3/generated/name/index.html +++ b/v2.0.3/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                              Rational numbers

                                              Rational numbers

                                              In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                              x = 1//3
                                              1//3
                                              y = 2//5
                                              2//5

                                              When adding x and y together we obtain a new rational number:

                                              z = x + y
                                              11//15
                                              +Rational numbers · Literate.jl
                                              Rational numbers

                                              Rational numbers

                                              In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                              x = 1//3
                                              1//3
                                              y = 2//5
                                              2//5

                                              When adding x and y together we obtain a new rational number:

                                              z = x + y
                                              11//15
                                              \ No newline at end of file diff --git a/v2.0.3/index.html b/v2.0.3/index.html index 7eb9e3c..0e4267f 100644 --- a/v2.0.3/index.html +++ b/v2.0.3/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                              1. Introduction

                                              1. Introduction

                                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                              What?

                                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                              The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                              Why?

                                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                              It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                              +1. Introduction · Literate.jl
                                              1. Introduction

                                              1. Introduction

                                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                              What?

                                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                              The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                              Why?

                                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                              It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                              \ No newline at end of file diff --git a/v2.0.3/outputformats/index.html b/v2.0.3/outputformats/index.html index c4c7eaf..6fd49df 100644 --- a/v2.0.3/outputformats/index.html +++ b/v2.0.3/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                              4. Output Formats

                                              4. Output Formats

                                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                              # # Rational numbers
+4. Output Formats · Literate.jl
                                              4. Output Formats
                                              4. Output Formats
                                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                              and see how this is rendered in each of the output formats.
                                              4.1. Markdown Output
                                              The (default) markdown output of the source snippet above is as follows
                                              ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
                                              and see how this is rendered in each of the output formats.
                                              4.1. Markdown Output
                                              The (default) markdown output of the source snippet above is as follows
                                              ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                              Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                              Literate.markdown — Function.
                                              Literate.markdown(inputfile, outputdir; kwargs...)
                                              Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                              Keyword arguments:
                                              • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                              • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                              • codefence: A Pair of opening and closing code fence. Defaults to
                                                "```@example $(name)" => "```"
                                                if documenter = true and
                                                "```julia" => "```"
                                                if documenter = false.
                                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                              source
                                              4.2. Notebook Output
                                              The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                              Literate.notebook — Function.
                                              Literate.notebook(inputfile, outputdir; kwargs...)
                                              Generate a notebook from inputfile and write the result to outputdir.
                                              Keyword arguments:
                                              • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                              • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                              source
                                              Notebook metadata
                                              Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                              %% optional ignored text [type] {optional metadata JSON}
                                              Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                              4.3. Script Output
                                              The (default) script output of the source snippet above is as follows
                                              x = 1//3
+```
                                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                              Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                              Literate.markdown — Function.
                                              Literate.markdown(inputfile, outputdir; kwargs...)
                                              Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                              Keyword arguments:
                                              • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                              • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                              • codefence: A Pair of opening and closing code fence. Defaults to
                                                "```@example $(name)" => "```"
                                                if documenter = true and
                                                "```julia" => "```"
                                                if documenter = false.
                                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                              source
                                              4.2. Notebook Output
                                              The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                              Literate.notebook — Function.
                                              Literate.notebook(inputfile, outputdir; kwargs...)
                                              Generate a notebook from inputfile and write the result to outputdir.
                                              Keyword arguments:
                                              • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                              • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                              source
                                              Notebook metadata
                                              Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                              %% optional ignored text [type] {optional metadata JSON}
                                              Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                              4.3. Script Output
                                              The (default) script output of the source snippet above is as follows
                                              x = 1//3
 
 y = 2//5
 
-z = x + y
                                              We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                                              Literate.script — Function.
                                              Literate.script(inputfile, outputdir; kwargs...)
                                              Generate a plain script file from inputfile and write the result to outputdir.
                                              Keyword arguments:
                                              • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                              • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                              source
                                              
+z = x + y

                                              We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                                              Literate.script — Function.
                                              Literate.script(inputfile, outputdir; kwargs...)

                                              Generate a plain script file from inputfile and write the result to outputdir.

                                              Keyword arguments:

                                              • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                              • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                              • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                              • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                              • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                              source
                                              \ No newline at end of file diff --git a/v2.0.3/pipeline/index.html b/v2.0.3/pipeline/index.html index 2712f81..ee291b8 100644 --- a/v2.0.3/pipeline/index.html +++ b/v2.0.3/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                              3. Processing pipeline

                                              3. Processing pipeline

                                              The generation of output follows the same pipeline for all output formats:

                                              1. Pre-processing
                                              2. Parsing
                                              3. Document generation
                                              4. Post-processing
                                              5. Writing to file

                                              3.1. Pre-processing

                                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                              3.2. Parsing

                                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                              # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                              3. Processing pipeline
                                              3. Processing pipeline
                                              The generation of output follows the same pipeline for all output formats:
                                              1. Pre-processing
                                              2. Parsing
                                              3. Document generation
                                              4. Post-processing
                                              5. Writing to file
                                              3.1. Pre-processing
                                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                              3.2. Parsing
                                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                              Chunk #2:
                                              # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                              Chunk #3:
                                              When adding `x` and `y` together we obtain a new rational number:
                                              Chunk #4:
                                              z = x + y
                                              It is then up to the Document generation step to decide how these chunks should be treated.
                                              Custom control over chunk splits
                                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                              x = 1 // 3
+y = 2 // 5
                                              Chunk #3:
                                              When adding `x` and `y` together we obtain a new rational number:
                                              Chunk #4:
                                              z = x + y
                                              It is then up to the Document generation step to decide how these chunks should be treated.
                                              Custom control over chunk splits
                                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                              x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                              The example above would result in two consecutive code-chunks.
                                              Tip
                                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                              It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                              3.3. Document generation
                                              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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                              • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                              3.4. Post-processing
                                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                              3.5. Writing to file
                                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                              
+z = x + y

                                              The example above would result in two consecutive code-chunks.

                                              Tip

                                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                              It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                              3.3. Document generation

                                              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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                              • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                              3.4. Post-processing

                                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                              3.5. Writing to file

                                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                              \ No newline at end of file diff --git a/v2.0.3/search/index.html b/v2.0.3/search/index.html index c9635ef..7b689b4 100644 --- a/v2.0.3/search/index.html +++ b/v2.0.3/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
                                              Search

                                              Search

                                              Number of results: loading...

                                                +Search · Literate.jl
                                                Search

                                                Search

                                                Number of results: loading...

                                                  \ No newline at end of file diff --git a/v2.0.4/customprocessing/index.html b/v2.0.4/customprocessing/index.html index c042d88..edfc29a 100644 --- a/v2.0.4/customprocessing/index.html +++ b/v2.0.4/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                  5. Custom pre- and post-processing

                                                  5. Custom pre- and post-processing

                                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                  Example: Adding current date

                                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                  # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                  5. Custom pre- and post-processing
                                                  5. Custom pre- and post-processing
                                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                  Example: Adding current date
                                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                  # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                  where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                  function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                  Example: Replacing include calls with included code
                                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                  # # Replace includes
+end
                                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                  Example: Replacing include calls with included code
                                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                  # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                  function replace_includes(str)
+include("file2.jl")
                                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                  function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                  (of course replace included with your respective files)
                                                  Finally, you simply pass this function to e.g. Literate.markdown as
                                                  Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                  This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                  
+end

                                                  (of course replace included with your respective files)

                                                  Finally, you simply pass this function to e.g. Literate.markdown as

                                                  Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                  This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                  \ No newline at end of file diff --git a/v2.0.4/documenter/index.html b/v2.0.4/documenter/index.html index 4dd45f7..caf5e65 100644 --- a/v2.0.4/documenter/index.html +++ b/v2.0.4/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                  6. Interaction with Documenter.jl

                                                  6. Interaction with Documenter.jl

                                                  Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                                  Literate.markdown:

                                                  • The default code fence will change from
                                                    ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                    6. Interaction with Documenter.jl
                                                    6. Interaction with Documenter.jl
                                                    Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                    Literate.markdown:
                                                    • The default code fence will change from
                                                      ```julia
 # code
 ```
                                                      to Documenters @example blocks:
                                                      ```@examples $(name)
 # code
-```
                                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                      ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                    Literate.notebook:
                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                    • Documenter style markdown math
                                                      ```math
+```
                                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                      ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                    Literate.notebook:
                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                    • Documenter style markdown math
                                                      ```math
 \int f dx
 ```
                                                      is replaced with notebook compatible
                                                      $$
 \int f dx
-$$
                                                    Literate.script:
                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                    
+$$

                                                  Literate.script:

                                                  • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                  \ No newline at end of file diff --git a/v2.0.4/fileformat/index.html b/v2.0.4/fileformat/index.html index effedf6..e3d434f 100644 --- a/v2.0.4/fileformat/index.html +++ b/v2.0.4/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                  2. File Format

                                                  2. File Format

                                                  The source file format for Literate 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.

                                                  2.1. Syntax

                                                  The basic syntax is simple:

                                                  • lines starting with # are treated as markdown,
                                                  • all other lines are treated as julia code.

                                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                  Lets look at a simple example:

                                                  # # Rational numbers
+2. File Format · Literate.jl
                                                  2. File Format
                                                  2. File Format
                                                  The source file format for Literate 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.
                                                  2.1. Syntax
                                                  The basic syntax is simple:
                                                  • lines starting with # are treated as markdown,
                                                  • all other lines are treated as julia code.
                                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                  Lets look at a simple example:
                                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                  2.2. Filtering Lines
                                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                  • #md: line exclusive to markdown output,
                                                  • #nb: line exclusive to notebook output,
                                                  • #jl: line exclusive to script output,
                                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                  Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                  Tip
                                                  The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                  #md # ```@docs
+z = x + y
                                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                  2.2. Filtering Lines
                                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                  • #md: line exclusive to markdown output,
                                                  • #nb: line exclusive to notebook output,
                                                  • #jl: line exclusive to script output,
                                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                  Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                  Tip
                                                  The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                  #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                  The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                  using Test                      #src
-@test result == expected_result #src
                                                  2.3. Default Replacements
                                                  The following convenience "macros" are always expanded:
                                                  • @__NAME__
                                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                  • @__REPO_ROOT_URL__
                                                    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.
                                                  • @__NBVIEWER_ROOT_URL__
                                                    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                                                  • @__BINDER_ROOT_URL__
                                                    expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:
                                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                  Note
                                                  @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.
                                                  
+@test result == expected_result #src

                                                  2.3. Default Replacements

                                                  The following convenience "macros" are always expanded:

                                                  • @__NAME__

                                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                  • @__REPO_ROOT_URL__

                                                    expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.

                                                  • @__NBVIEWER_ROOT_URL__

                                                    expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                                                  • @__BINDER_ROOT_URL__

                                                    expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:

                                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                  Note

                                                  @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.

                                                  \ No newline at end of file diff --git a/v2.0.4/generated/example/index.html b/v2.0.4/generated/example/index.html index b488ea0..977cd44 100644 --- a/v2.0.4/generated/example/index.html +++ b/v2.0.4/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                                  7. Example

                                                  7. Example

                                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                  Basic syntax

                                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                  x = 1//3
-y = 2//5
                                                  2//5

                                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                  • This line starts with #md and is thus only visible in the markdown output.

                                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                  x + y
                                                  11//15
                                                  x * y
                                                  2//15

                                                  Output Capturing

                                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                  Note

                                                  Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                  function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                                  7. Example
                                                  7. Example
                                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                  Basic syntax
                                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                  x = 1//3
+y = 2//5
                                                  2//5
                                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                  • This line starts with #md and is thus only visible in the markdown output.
                                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                  x + y
                                                  11//15
                                                  x * y
                                                  2//15
                                                  Output Capturing
                                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                  Note
                                                  Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                  function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                                  4-element Array{Int64,1}:
  1
  2
  3
- 4
                                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                  using Plots
+ 4
                                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                  using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                  
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
   2247.98,1028.05 2250.12,1015.72 2252.26,1003.31 2254.4,990.826 2256.54,978.267 2258.68,965.638 2260.82,952.944 2262.95,940.191 2265.09,927.382 2267.23,914.522
   2269.37,901.615 2271.51,888.667 2273.65,875.681 2275.79,862.663 2277.93,849.617 2280.07,836.548 2282.21,823.459 2284.35,810.357 2286.49,797.246 2288.63,784.13
 
-  "/>
-
   2247.98,133.151 2250.12,128.665 2252.26,124.412 2254.4,120.394 2256.54,116.612 2258.68,113.068 2260.82,109.763 2262.95,106.698 2265.09,103.874 2267.23,101.292
   2269.37,98.9539 2271.51,96.8592 2273.65,95.0092 2275.79,93.4045 2277.93,92.0458 2280.07,90.9334 2282.21,90.0678 2284.35,89.4493 2286.49,89.0781 2288.63,88.9544
 
-  "/>
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                                  Custom processing
                                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                  z = 1.0 + 2.0im
                                                  1.0 + 2.0im
                                                  Documenter.jl interaction
                                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                  This page was generated using Literate.jl.
                                                  
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                                  Custom processing
                                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                  z = 1.0 + 2.0im
                                                  1.0 + 2.0im
                                                  Documenter.jl interaction
                                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                  This page was generated using Literate.jl.
                                                  \ No newline at end of file diff --git a/v2.0.4/generated/name/index.html b/v2.0.4/generated/name/index.html index 2bd4ddf..cad3560 100644 --- a/v2.0.4/generated/name/index.html +++ b/v2.0.4/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                  Rational numbers

                                                  Rational numbers

                                                  In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                  x = 1//3
                                                  1//3
                                                  y = 2//5
                                                  2//5

                                                  When adding x and y together we obtain a new rational number:

                                                  z = x + y
                                                  11//15
                                                  +Rational numbers · Literate.jl
                                                  Rational numbers

                                                  Rational numbers

                                                  In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                  x = 1//3
                                                  1//3
                                                  y = 2//5
                                                  2//5

                                                  When adding x and y together we obtain a new rational number:

                                                  z = x + y
                                                  11//15
                                                  \ No newline at end of file diff --git a/v2.0.4/index.html b/v2.0.4/index.html index 7eb9e3c..0e4267f 100644 --- a/v2.0.4/index.html +++ b/v2.0.4/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                  1. Introduction

                                                  1. Introduction

                                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                  What?

                                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                  The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                  Why?

                                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                  +1. Introduction · Literate.jl
                                                  1. Introduction

                                                  1. Introduction

                                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                  What?

                                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                  The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                  Why?

                                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                  \ No newline at end of file diff --git a/v2.0.4/outputformats/index.html b/v2.0.4/outputformats/index.html index ab95b5b..63b2f11 100644 --- a/v2.0.4/outputformats/index.html +++ b/v2.0.4/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                  4. Output Formats

                                                  4. Output Formats

                                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                  # # Rational numbers
+4. Output Formats · Literate.jl
                                                  4. Output Formats
                                                  4. Output Formats
                                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,8 +51,8 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                  and see how this is rendered in each of the output formats.
                                                  4.1. Markdown Output
                                                  The (default) markdown output of the source snippet above is as follows
                                                  ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+z = x + y
                                                  and see how this is rendered in each of the output formats.
                                                  4.1. Markdown Output
                                                  The (default) markdown output of the source snippet above is as follows
                                                  ```@meta
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                  Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                                  Literate.markdown — Function.
                                                  Literate.markdown(inputfile, outputdir; kwargs...)
                                                  Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                                  Keyword arguments:
                                                  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                                  • codefence: A Pair of opening and closing code fence. Defaults to
                                                    "```@example $(name)" => "```"
                                                    if documenter = true and
                                                    "```julia" => "```"
                                                    if documenter = false.
                                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                  source
                                                  4.2. Notebook Output
                                                  The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                                  Literate.notebook — Function.
                                                  Literate.notebook(inputfile, outputdir; kwargs...)
                                                  Generate a notebook from inputfile and write the result to outputdir.
                                                  Keyword arguments:
                                                  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                  source
                                                  Notebook metadata
                                                  Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                  %% optional ignored text [type] {optional metadata JSON}
                                                  Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                  4.3. Script Output
                                                  The (default) script output of the source snippet above is as follows
                                                  x = 1//3
+```
                                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                  Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                                  Literate.markdown — Function.
                                                  Literate.markdown(inputfile, outputdir; kwargs...)
                                                  Generate a markdown file from inputfile and write the result to the directoryoutputdir.
                                                  Keyword arguments:
                                                  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.
                                                  • codefence: A Pair of opening and closing code fence. Defaults to
                                                    "```@example $(name)" => "```"
                                                    if documenter = true and
                                                    "```julia" => "```"
                                                    if documenter = false.
                                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                  source
                                                  4.2. Notebook Output
                                                  The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                                  Literate.notebook — Function.
                                                  Literate.notebook(inputfile, outputdir; kwargs...)
                                                  Generate a notebook from inputfile and write the result to outputdir.
                                                  Keyword arguments:
                                                  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                  source
                                                  Notebook metadata
                                                  Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                  %% optional ignored text [type] {optional metadata JSON}
                                                  Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                  4.3. Script Output
                                                  The (default) script output of the source snippet above is as follows
                                                  x = 1//3
 
 y = 2//5
 
-z = x + y
                                                  We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                                                  Literate.script — Function.
                                                  Literate.script(inputfile, outputdir; kwargs...)
                                                  Generate a plain script file from inputfile and write the result to outputdir.
                                                  Keyword arguments:
                                                  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                  source
                                                  
+z = x + y

                                                  We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                                                  Literate.script — Function.
                                                  Literate.script(inputfile, outputdir; kwargs...)

                                                  Generate a plain script file from inputfile and write the result to outputdir.

                                                  Keyword arguments:

                                                  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                  • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                                  • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                  source
                                                  \ No newline at end of file diff --git a/v2.0.4/pipeline/index.html b/v2.0.4/pipeline/index.html index 2712f81..ee291b8 100644 --- a/v2.0.4/pipeline/index.html +++ b/v2.0.4/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                  3. Processing pipeline

                                                  3. Processing pipeline

                                                  The generation of output follows the same pipeline for all output formats:

                                                  1. Pre-processing
                                                  2. Parsing
                                                  3. Document generation
                                                  4. Post-processing
                                                  5. Writing to file

                                                  3.1. Pre-processing

                                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                  3.2. Parsing

                                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                  # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                  3. Processing pipeline
                                                  3. Processing pipeline
                                                  The generation of output follows the same pipeline for all output formats:
                                                  1. Pre-processing
                                                  2. Parsing
                                                  3. Document generation
                                                  4. Post-processing
                                                  5. Writing to file
                                                  3.1. Pre-processing
                                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                  3.2. Parsing
                                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                  Chunk #2:
                                                  # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                  Chunk #3:
                                                  When adding `x` and `y` together we obtain a new rational number:
                                                  Chunk #4:
                                                  z = x + y
                                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                                  Custom control over chunk splits
                                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                  x = 1 // 3
+y = 2 // 5
                                                  Chunk #3:
                                                  When adding `x` and `y` together we obtain a new rational number:
                                                  Chunk #4:
                                                  z = x + y
                                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                                  Custom control over chunk splits
                                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                  x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                  The example above would result in two consecutive code-chunks.
                                                  Tip
                                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                  It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                  3.3. Document generation
                                                  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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                  3.4. Post-processing
                                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                  3.5. Writing to file
                                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                  
+z = x + y

                                                  The example above would result in two consecutive code-chunks.

                                                  Tip

                                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                  It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                  3.3. Document generation

                                                  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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                  3.4. Post-processing

                                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                  3.5. Writing to file

                                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                  \ No newline at end of file diff --git a/v2.0.4/search/index.html b/v2.0.4/search/index.html index c9635ef..7b689b4 100644 --- a/v2.0.4/search/index.html +++ b/v2.0.4/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl
                                                  Search

                                                  Search

                                                  Number of results: loading...

                                                    +Search · Literate.jl
                                                    Search

                                                    Search

                                                    Number of results: loading...

                                                      \ No newline at end of file diff --git a/v2.1.0/customprocessing.html b/v2.1.0/customprocessing.html index ff53385..724adda 100644 --- a/v2.1.0/customprocessing.html +++ b/v2.1.0/customprocessing.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                      Edit on GitHub

                                                      5. Custom pre- and post-processing

                                                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                      Example: Adding current date

                                                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                      # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                      Edit on GitHub
                                                      5. Custom pre- and post-processing
                                                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                      Example: Adding current date
                                                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                      # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                      where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                      function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                      Example: Replacing include calls with included code
                                                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                      # # Replace includes
+end
                                                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                      Example: Replacing include calls with included code
                                                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                      # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                      function replace_includes(str)
+include("file2.jl")
                                                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                      function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                      (of course replace included with your respective files)
                                                      Finally, you simply pass this function to e.g. Literate.markdown as
                                                      Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                      This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                      
+end

                                                      (of course replace included with your respective files)

                                                      Finally, you simply pass this function to e.g. Literate.markdown as

                                                      Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                      This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                      \ No newline at end of file diff --git a/v2.1.0/documenter.html b/v2.1.0/documenter.html index 34cb052..33fc836 100644 --- a/v2.1.0/documenter.html +++ b/v2.1.0/documenter.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                      Edit on GitHub

                                                      6. Interaction with Documenter.jl

                                                      Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                                      Literate.markdown:

                                                      • The default code fence will change from
                                                        ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                        Edit on GitHub
                                                        6. Interaction with Documenter.jl
                                                        Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                        Literate.markdown:
                                                        • The default code fence will change from
                                                          ```julia
 # code
 ```
                                                          to Documenters @example blocks:
                                                          ```@examples $(name)
 # code
-```
                                                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                          ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                          ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
 ```
                                                        Literate.notebook:
                                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                        • Documenter style markdown math
                                                          ```math
 \int f dx
 ```
                                                          is replaced with notebook compatible
                                                          $$
 \int f dx
-$$
                                                        Literate.script:
                                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                        
+$$

                                                      Literate.script:

                                                      • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                      \ No newline at end of file diff --git a/v2.1.0/fileformat.html b/v2.1.0/fileformat.html index 2ef3b97..999a154 100644 --- a/v2.1.0/fileformat.html +++ b/v2.1.0/fileformat.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                      Edit on GitHub

                                                      2. File Format

                                                      The source file format for Literate 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.

                                                      2.1. Syntax

                                                      The basic syntax is simple:

                                                      • lines starting with # are treated as markdown,
                                                      • all other lines are treated as julia code.

                                                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                      Lets look at a simple example:

                                                      # # Rational numbers
+2. File Format · Literate.jl
                                                      Edit on GitHub
                                                      2. File Format
                                                      The source file format for Literate 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.
                                                      2.1. Syntax
                                                      The basic syntax is simple:
                                                      • lines starting with # are treated as markdown,
                                                      • all other lines are treated as julia code.
                                                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                      Lets look at a simple example:
                                                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                      For simple use this is all you need to know. The following additional special syntax can also be used:
                                                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                      2.2. Filtering Lines
                                                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                      • #md: line exclusive to markdown output,
                                                      • #nb: line exclusive to notebook output,
                                                      • #jl: line exclusive to script output,
                                                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                      Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                      Tip
                                                      The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                      #md # ```@docs
+z = x + y
                                                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                      For simple use this is all you need to know. The following additional special syntax can also be used:
                                                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                      2.2. Filtering Lines
                                                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                      • #md: line exclusive to markdown output,
                                                      • #nb: line exclusive to notebook output,
                                                      • #jl: line exclusive to script output,
                                                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                      Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                      Tip
                                                      The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                      #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                      The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                      using Test                      #src
-@test result == expected_result #src
                                                      2.3. Default Replacements
                                                      The following convenience "macros" are always expanded:
                                                      • @__NAME__
                                                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                      • @__REPO_ROOT_URL__
                                                        expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.
                                                      • @__NBVIEWER_ROOT_URL__
                                                        expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                                                      • @__BINDER_ROOT_URL__
                                                        expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:
                                                        [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                      Note
                                                      @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.
                                                      
+@test result == expected_result #src

                                                      2.3. Default Replacements

                                                      The following convenience "macros" are always expanded:

                                                      • @__NAME__

                                                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                      • @__REPO_ROOT_URL__

                                                        expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.

                                                      • @__NBVIEWER_ROOT_URL__

                                                        expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                                                      • @__BINDER_ROOT_URL__

                                                        expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:

                                                        [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                      Note

                                                      @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.

                                                      \ No newline at end of file diff --git a/v2.1.0/generated/example.html b/v2.1.0/generated/example.html index c86597c..2d372d2 100644 --- a/v2.1.0/generated/example.html +++ b/v2.1.0/generated/example.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                                      Edit on GitHub

                                                      7. Example

                                                      This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                      Basic syntax

                                                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                      x = 1//3
-y = 2//5
                                                      2//5

                                                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                      • This line starts with #md and is thus only visible in the markdown output.

                                                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                      x + y
                                                      11//15
                                                      x * y
                                                      2//15

                                                      Output Capturing

                                                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                      Note

                                                      Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                      function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                                      Edit on GitHub
                                                      7. Example
                                                      This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                      Basic syntax
                                                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                      x = 1//3
+y = 2//5
                                                      2//5
                                                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                      • This line starts with #md and is thus only visible in the markdown output.
                                                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                      x + y
                                                      11//15
                                                      x * y
                                                      2//15
                                                      Output Capturing
                                                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                      Note
                                                      Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                      function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                                      4-element Array{Int64,1}:
  1
  2
  3
- 4
                                                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                      using Plots
+ 4
                                                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                      using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                      
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
-
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                                      Custom processing
                                                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                      z = 1.0 + 2.0im
                                                      1.0 + 2.0im
                                                      Documenter.jl interaction
                                                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                      This page was generated using Literate.jl.
                                                      
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                                      Custom processing
                                                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                      z = 1.0 + 2.0im
                                                      1.0 + 2.0im
                                                      Documenter.jl interaction
                                                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                      This page was generated using Literate.jl.
                                                      \ No newline at end of file diff --git a/v2.1.0/generated/name.html b/v2.1.0/generated/name.html index ea2c1d5..016eaca 100644 --- a/v2.1.0/generated/name.html +++ b/v2.1.0/generated/name.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                      Edit on GitHub

                                                      Rational numbers

                                                      In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                      x = 1//3
                                                      1//3
                                                      y = 2//5
                                                      2//5

                                                      When adding x and y together we obtain a new rational number:

                                                      z = x + y
                                                      11//15
                                                      +Rational numbers · Literate.jl
                                                      Edit on GitHub

                                                      Rational numbers

                                                      In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                      x = 1//3
                                                      1//3
                                                      y = 2//5
                                                      2//5

                                                      When adding x and y together we obtain a new rational number:

                                                      z = x + y
                                                      11//15
                                                      \ No newline at end of file diff --git a/v2.1.0/index.html b/v2.1.0/index.html index 1b66f51..fea26e4 100644 --- a/v2.1.0/index.html +++ b/v2.1.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                      Edit on GitHub

                                                      1. Introduction

                                                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                      What?

                                                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                      Why?

                                                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                      It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                      +1. Introduction · Literate.jl
                                                      Edit on GitHub

                                                      1. Introduction

                                                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                      What?

                                                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                      Why?

                                                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                      It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                      \ No newline at end of file diff --git a/v2.1.0/outputformats.html b/v2.1.0/outputformats.html index 584296d..41a5956 100644 --- a/v2.1.0/outputformats.html +++ b/v2.1.0/outputformats.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                      Edit on GitHub

                                                      4. Output Formats

                                                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                      # # Rational numbers
+4. Output Formats · Literate.jl
                                                      Edit on GitHub
                                                      4. Output Formats
                                                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                      and see how this is rendered in each of the output formats.
                                                      4.1. Markdown Output
                                                      The (default) markdown output of the source snippet above is as follows
                                                      ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                      Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                                      Literate.markdown — Function.
                                                      Literate.markdown(inputfile, outputdir; kwargs...)
                                                      Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                      Keyword arguments:
                                                      • name: name of the output file, excluding .md; name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                      • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the manual section on Interaction with Documenter.
                                                      • codefence: A Pair of opening and closing code fence. Defaults to
                                                        "```@example $(name)" => "```"
                                                        if documenter = true and
                                                        "```julia" => "```"
                                                        if documenter = false.
                                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                      source
                                                      4.2. Notebook Output
                                                      The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                                      Literate.notebook — Function.
                                                      Literate.notebook(inputfile, outputdir; kwargs...)
                                                      Generate a notebook from inputfile and write the result to outputdir.
                                                      Keyword arguments:
                                                      • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                      • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                      source
                                                      Notebook metadata
                                                      Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                      %% optional ignored text [type] {optional metadata JSON}
                                                      Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                      4.3. Script Output
                                                      The (default) script output of the source snippet above is as follows
                                                      x = 1//3
+```
                                                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                      Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                                      Literate.markdown — Function.
                                                      Literate.markdown(inputfile, outputdir; kwargs...)
                                                      Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                      Keyword arguments:
                                                      • name: name of the output file, excluding .md; name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                      • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the manual section on Interaction with Documenter.
                                                      • codefence: A Pair of opening and closing code fence. Defaults to
                                                        "```@example $(name)" => "```"
                                                        if documenter = true and
                                                        "```julia" => "```"
                                                        if documenter = false.
                                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                      source
                                                      4.2. Notebook Output
                                                      The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                                      Literate.notebook — Function.
                                                      Literate.notebook(inputfile, outputdir; kwargs...)
                                                      Generate a notebook from inputfile and write the result to outputdir.
                                                      Keyword arguments:
                                                      • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                      • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                      source
                                                      Notebook metadata
                                                      Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                      %% optional ignored text [type] {optional metadata JSON}
                                                      Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                      4.3. Script Output
                                                      The (default) script output of the source snippet above is as follows
                                                      x = 1//3
 
 y = 2//5
 
-z = x + y
                                                      We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                                                      Literate.script — Function.
                                                      Literate.script(inputfile, outputdir; kwargs...)
                                                      Generate a plain script file from inputfile and write the result to outputdir.
                                                      Keyword arguments:
                                                      • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                      • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                      source
                                                      
+z = x + y

                                                      We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                                                      Literate.script — Function.
                                                      Literate.script(inputfile, outputdir; kwargs...)

                                                      Generate a plain script file from inputfile and write the result to outputdir.

                                                      Keyword arguments:

                                                      • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                      • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                      • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                      • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                                      • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                      source
                                                      \ No newline at end of file diff --git a/v2.1.0/pipeline.html b/v2.1.0/pipeline.html index 2afc761..a47ca9c 100644 --- a/v2.1.0/pipeline.html +++ b/v2.1.0/pipeline.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                      Edit on GitHub

                                                      3. Processing pipeline

                                                      The generation of output follows the same pipeline for all output formats:

                                                      1. Pre-processing
                                                      2. Parsing
                                                      3. Document generation
                                                      4. Post-processing
                                                      5. Writing to file

                                                      3.1. Pre-processing

                                                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                      3.2. Parsing

                                                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                      # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                      Edit on GitHub
                                                      3. Processing pipeline
                                                      The generation of output follows the same pipeline for all output formats:
                                                      1. Pre-processing
                                                      2. Parsing
                                                      3. Document generation
                                                      4. Post-processing
                                                      5. Writing to file
                                                      3.1. Pre-processing
                                                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                      3.2. Parsing
                                                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                      Chunk #2:
                                                      # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                      Chunk #3:
                                                      When adding `x` and `y` together we obtain a new rational number:
                                                      Chunk #4:
                                                      z = x + y
                                                      It is then up to the Document generation step to decide how these chunks should be treated.
                                                      Custom control over chunk splits
                                                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                      x = 1 // 3
+y = 2 // 5
                                                      Chunk #3:
                                                      When adding `x` and `y` together we obtain a new rational number:
                                                      Chunk #4:
                                                      z = x + y
                                                      It is then up to the Document generation step to decide how these chunks should be treated.
                                                      Custom control over chunk splits
                                                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                      x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                      The example above would result in two consecutive code-chunks.
                                                      Tip
                                                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                      It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                      3.3. Document generation
                                                      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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                      • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                      3.4. Post-processing
                                                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                      3.5. Writing to file
                                                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                      
+z = x + y

                                                      The example above would result in two consecutive code-chunks.

                                                      Tip

                                                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                      It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                      3.3. Document generation

                                                      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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                      • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                      3.4. Post-processing

                                                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                      3.5. Writing to file

                                                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                      \ No newline at end of file diff --git a/v2.1.0/search.html b/v2.1.0/search.html index 44dcd3e..dcee4c9 100644 --- a/v2.1.0/search.html +++ b/v2.1.0/search.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                      Loading search...

                                                        +Search · Literate.jl

                                                        Loading search...

                                                          \ No newline at end of file diff --git a/v2.1.1/customprocessing/index.html b/v2.1.1/customprocessing/index.html index e6ed22d..38247b2 100644 --- a/v2.1.1/customprocessing/index.html +++ b/v2.1.1/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                          Edit on GitHub

                                                          5. Custom pre- and post-processing

                                                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                          Example: Adding current date

                                                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                          # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                          Edit on GitHub
                                                          5. Custom pre- and post-processing
                                                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                          Example: Adding current date
                                                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                          # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                          where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                          function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                          Example: Replacing include calls with included code
                                                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                          # # Replace includes
+end
                                                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                          Example: Replacing include calls with included code
                                                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                          # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                          function replace_includes(str)
+include("file2.jl")
                                                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                          function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                          (of course replace included with your respective files)
                                                          Finally, you simply pass this function to e.g. Literate.markdown as
                                                          Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                          This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                          
+end

                                                          (of course replace included with your respective files)

                                                          Finally, you simply pass this function to e.g. Literate.markdown as

                                                          Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                          This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                          \ No newline at end of file diff --git a/v2.1.1/documenter/index.html b/v2.1.1/documenter/index.html index 52ea7e8..0c59338 100644 --- a/v2.1.1/documenter/index.html +++ b/v2.1.1/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                          Edit on GitHub

                                                          6. Interaction with Documenter.jl

                                                          Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                                          Literate.markdown:

                                                          • The default code fence will change from
                                                            ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                            Edit on GitHub
                                                            6. Interaction with Documenter.jl
                                                            Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                            Literate.markdown:
                                                            • The default code fence will change from
                                                              ```julia
 # code
 ```
                                                              to Documenters @example blocks:
                                                              ```@examples $(name)
 # code
-```
                                                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                              ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                              ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
 ```
                                                            Literate.notebook:
                                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                            • Documenter style markdown math
                                                              ```math
 \int f dx
 ```
                                                              is replaced with notebook compatible
                                                              $$
 \int f dx
-$$
                                                            Literate.script:
                                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                            
+$$

                                                          Literate.script:

                                                          • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                          \ No newline at end of file diff --git a/v2.1.1/fileformat/index.html b/v2.1.1/fileformat/index.html index be0ed7b..74ee57f 100644 --- a/v2.1.1/fileformat/index.html +++ b/v2.1.1/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                          Edit on GitHub

                                                          2. File Format

                                                          The source file format for Literate 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.

                                                          2.1. Syntax

                                                          The basic syntax is simple:

                                                          • lines starting with # are treated as markdown,
                                                          • all other lines are treated as julia code.

                                                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                          Lets look at a simple example:

                                                          # # Rational numbers
+2. File Format · Literate.jl
                                                          Edit on GitHub
                                                          2. File Format
                                                          The source file format for Literate 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.
                                                          2.1. Syntax
                                                          The basic syntax is simple:
                                                          • lines starting with # are treated as markdown,
                                                          • all other lines are treated as julia code.
                                                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                          Lets look at a simple example:
                                                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                          For simple use this is all you need to know. The following additional special syntax can also be used:
                                                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                          2.2. Filtering Lines
                                                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                          • #md: line exclusive to markdown output,
                                                          • #nb: line exclusive to notebook output,
                                                          • #jl: line exclusive to script output,
                                                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                          Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                          Tip
                                                          The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                          #md # ```@docs
+z = x + y
                                                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                          For simple use this is all you need to know. The following additional special syntax can also be used:
                                                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                          2.2. Filtering Lines
                                                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                          • #md: line exclusive to markdown output,
                                                          • #nb: line exclusive to notebook output,
                                                          • #jl: line exclusive to script output,
                                                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                          Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                          Tip
                                                          The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                          #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                          The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                          using Test                      #src
-@test result == expected_result #src
                                                          2.3. Default Replacements
                                                          The following convenience "macros" are always expanded:
                                                          • @__NAME__
                                                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                          • @__REPO_ROOT_URL__
                                                            expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.
                                                          • @__NBVIEWER_ROOT_URL__
                                                            expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.
                                                          • @__BINDER_ROOT_URL__
                                                            expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:
                                                            [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                          Note
                                                          @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.
                                                          
+@test result == expected_result #src

                                                          2.3. Default Replacements

                                                          The following convenience "macros" are always expanded:

                                                          • @__NAME__

                                                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                          • @__REPO_ROOT_URL__

                                                            expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module.

                                                          • @__NBVIEWER_ROOT_URL__

                                                            expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder) where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.

                                                          • @__BINDER_ROOT_URL__

                                                            expands to https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder) where branch/folder is the branch and folder where Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in https://mybinder.org/. To add a binder-badge in e.g. the HTML output you can use:

                                                            [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                          Note

                                                          @__REPO_ROOT_URL__ and @__NBVIEWER_ROOT_URL__ works for documentation built with DocumentationGenerator.jl but @__BINDER_ROOT_URL__ does not, since mybinder.org requires the files to be located inside a git repository.

                                                          \ No newline at end of file diff --git a/v2.1.1/generated/example/index.html b/v2.1.1/generated/example/index.html index f881570..98144a6 100644 --- a/v2.1.1/generated/example/index.html +++ b/v2.1.1/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                                          Edit on GitHub

                                                          7. Example

                                                          This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                          Basic syntax

                                                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                          x = 1//3
-y = 2//5
                                                          2//5

                                                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                          • This line starts with #md and is thus only visible in the markdown output.

                                                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                          x + y
                                                          11//15
                                                          x * y
                                                          2//15

                                                          Output Capturing

                                                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                          Note

                                                          Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                          function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                                          Edit on GitHub
                                                          7. Example
                                                          This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                          Basic syntax
                                                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                          x = 1//3
+y = 2//5
                                                          2//5
                                                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                          • This line starts with #md and is thus only visible in the markdown output.
                                                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                          x + y
                                                          11//15
                                                          x * y
                                                          2//15
                                                          Output Capturing
                                                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                          Note
                                                          Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                          function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                                          4-element Array{Int64,1}:
  1
  2
  3
- 4
                                                          Just like in the REPL, outputs ending with a semicolon hides the output:
                                                          1 + 1;
                                                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                          using Plots
+ 4
                                                          Just like in the REPL, outputs ending with a semicolon hides the output:
                                                          1 + 1;
                                                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                          using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                          
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
-
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                                          Custom processing
                                                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                          z = 1.0 + 2.0im
                                                          1.0 + 2.0im
                                                          Documenter.jl interaction
                                                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                          This page was generated using Literate.jl.
                                                          
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                                          Custom processing
                                                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                          z = 1.0 + 2.0im
                                                          1.0 + 2.0im
                                                          Documenter.jl interaction
                                                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                          This page was generated using Literate.jl.
                                                          \ No newline at end of file diff --git a/v2.1.1/generated/name/index.html b/v2.1.1/generated/name/index.html index a7e68c9..fedb1d3 100644 --- a/v2.1.1/generated/name/index.html +++ b/v2.1.1/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                          Edit on GitHub

                                                          Rational numbers

                                                          In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                          x = 1//3
                                                          1//3
                                                          y = 2//5
                                                          2//5

                                                          When adding x and y together we obtain a new rational number:

                                                          z = x + y
                                                          11//15
                                                          +Rational numbers · Literate.jl
                                                          Edit on GitHub

                                                          Rational numbers

                                                          In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                          x = 1//3
                                                          1//3
                                                          y = 2//5
                                                          2//5

                                                          When adding x and y together we obtain a new rational number:

                                                          z = x + y
                                                          11//15
                                                          \ No newline at end of file diff --git a/v2.1.1/index.html b/v2.1.1/index.html index 15bd5b9..39baa68 100644 --- a/v2.1.1/index.html +++ b/v2.1.1/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                          Edit on GitHub

                                                          1. Introduction

                                                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                          What?

                                                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                          Why?

                                                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                          It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                          +1. Introduction · Literate.jl
                                                          Edit on GitHub

                                                          1. Introduction

                                                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                          What?

                                                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                          Why?

                                                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                          It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                          \ No newline at end of file diff --git a/v2.1.1/outputformats/index.html b/v2.1.1/outputformats/index.html index bbdc373..fd3af56 100644 --- a/v2.1.1/outputformats/index.html +++ b/v2.1.1/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                          Edit on GitHub

                                                          4. Output Formats

                                                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                          # # Rational numbers
+4. Output Formats · Literate.jl
                                                          Edit on GitHub
                                                          4. Output Formats
                                                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                          and see how this is rendered in each of the output formats.
                                                          4.1. Markdown Output
                                                          The (default) markdown output of the source snippet above is as follows
                                                          ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                          Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                                          Literate.markdown — Function
                                                          Literate.markdown(inputfile, outputdir; kwargs...)
                                                          Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                          Keyword arguments:
                                                          • name: name of the output file, excluding .md; name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                          • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the manual section on Interaction with Documenter.
                                                          • codefence: A Pair of opening and closing code fence. Defaults to
                                                            "```@example $(name)" => "```"
                                                            if documenter = true and
                                                            "```julia" => "```"
                                                            if documenter = false.
                                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                          source
                                                          4.2. Notebook Output
                                                          The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                                          Literate.notebook — Function
                                                          Literate.notebook(inputfile, outputdir; kwargs...)
                                                          Generate a notebook from inputfile and write the result to outputdir.
                                                          Keyword arguments:
                                                          • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                          • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                          source
                                                          Notebook metadata
                                                          Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                          %% optional ignored text [type] {optional metadata JSON}
                                                          Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                          4.3. Script Output
                                                          The (default) script output of the source snippet above is as follows
                                                          x = 1//3
+```
                                                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                          Some of the output rendering can be controlled with keyword arguments to Literate.markdown:
                                                          Literate.markdown — Function
                                                          Literate.markdown(inputfile, outputdir; kwargs...)
                                                          Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                          Keyword arguments:
                                                          • name: name of the output file, excluding .md; name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.
                                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                          • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the manual section on Interaction with Documenter.
                                                          • codefence: A Pair of opening and closing code fence. Defaults to
                                                            "```@example $(name)" => "```"
                                                            if documenter = true and
                                                            "```julia" => "```"
                                                            if documenter = false.
                                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                          source
                                                          4.2. Notebook Output
                                                          The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:
                                                          Literate.notebook — Function
                                                          Literate.notebook(inputfile, outputdir; kwargs...)
                                                          Generate a notebook from inputfile and write the result to outputdir.
                                                          Keyword arguments:
                                                          • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                          • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.
                                                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                          source
                                                          Notebook metadata
                                                          Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                          %% optional ignored text [type] {optional metadata JSON}
                                                          Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                          4.3. Script Output
                                                          The (default) script output of the source snippet above is as follows
                                                          x = 1//3
 
 y = 2//5
 
-z = x + y
                                                          We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:
                                                          Literate.script — Function
                                                          Literate.script(inputfile, outputdir; kwargs...)
                                                          Generate a plain script file from inputfile and write the result to outputdir.
                                                          Keyword arguments:
                                                          • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                          • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                          source
                                                          
+z = x + y

                                                          We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

                                                          Literate.script — Function
                                                          Literate.script(inputfile, outputdir; kwargs...)

                                                          Generate a plain script file from inputfile and write the result to outputdir.

                                                          Keyword arguments:

                                                          • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.
                                                          • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.
                                                          • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.
                                                          • keep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.
                                                          • credit: boolean that controls the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this to the default, which is true.
                                                          source
                                                          \ No newline at end of file diff --git a/v2.1.1/pipeline/index.html b/v2.1.1/pipeline/index.html index 0c7e327..61a3c7a 100644 --- a/v2.1.1/pipeline/index.html +++ b/v2.1.1/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                          Edit on GitHub

                                                          3. Processing pipeline

                                                          The generation of output follows the same pipeline for all output formats:

                                                          1. Pre-processing
                                                          2. Parsing
                                                          3. Document generation
                                                          4. Post-processing
                                                          5. Writing to file

                                                          3.1. Pre-processing

                                                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                          3.2. Parsing

                                                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                          # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                          Edit on GitHub
                                                          3. Processing pipeline
                                                          The generation of output follows the same pipeline for all output formats:
                                                          1. Pre-processing
                                                          2. Parsing
                                                          3. Document generation
                                                          4. Post-processing
                                                          5. Writing to file
                                                          3.1. Pre-processing
                                                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                          3.2. Parsing
                                                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                          Chunk #2:
                                                          # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                          Chunk #3:
                                                          When adding `x` and `y` together we obtain a new rational number:
                                                          Chunk #4:
                                                          z = x + y
                                                          It is then up to the Document generation step to decide how these chunks should be treated.
                                                          Custom control over chunk splits
                                                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                          x = 1 // 3
+y = 2 // 5
                                                          Chunk #3:
                                                          When adding `x` and `y` together we obtain a new rational number:
                                                          Chunk #4:
                                                          z = x + y
                                                          It is then up to the Document generation step to decide how these chunks should be treated.
                                                          Custom control over chunk splits
                                                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                          x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                          The example above would result in two consecutive code-chunks.
                                                          Tip
                                                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                          It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                          3.3. Document generation
                                                          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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                          • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                          3.4. Post-processing
                                                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                          3.5. Writing to file
                                                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                          
+z = x + y

                                                          The example above would result in two consecutive code-chunks.

                                                          Tip

                                                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                          It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                          3.3. Document generation

                                                          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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                          • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                          3.4. Post-processing

                                                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                          3.5. Writing to file

                                                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                          \ No newline at end of file diff --git a/v2.1.1/search/index.html b/v2.1.1/search/index.html index 6212583..c97a31d 100644 --- a/v2.1.1/search/index.html +++ b/v2.1.1/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                          Loading search...

                                                            +Search · Literate.jl

                                                            Loading search...

                                                              \ No newline at end of file diff --git a/v2.2.0/customprocessing/index.html b/v2.2.0/customprocessing/index.html index 5dc28eb..0410b95 100644 --- a/v2.2.0/customprocessing/index.html +++ b/v2.2.0/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                              Edit on GitHub

                                                              5. Custom pre- and post-processing

                                                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                              Example: Adding current date

                                                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                              # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                              Edit on GitHub
                                                              5. Custom pre- and post-processing
                                                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                              Example: Adding current date
                                                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                              # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                              where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                              function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                              Example: Replacing include calls with included code
                                                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                              # # Replace includes
+end
                                                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                              Example: Replacing include calls with included code
                                                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                              # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                              function replace_includes(str)
+include("file2.jl")
                                                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                              function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                              (of course replace included with your respective files)
                                                              Finally, you simply pass this function to e.g. Literate.markdown as
                                                              Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                              This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                              
+end

                                                              (of course replace included with your respective files)

                                                              Finally, you simply pass this function to e.g. Literate.markdown as

                                                              Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                              This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                              \ No newline at end of file diff --git a/v2.2.0/documenter/index.html b/v2.2.0/documenter/index.html index 861b244..6151510 100644 --- a/v2.2.0/documenter/index.html +++ b/v2.2.0/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                              Edit on GitHub

                                                              6. Interaction with Documenter.jl

                                                              Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                                              Literate.markdown:

                                                              • The default code fence will change from
                                                                ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                Edit on GitHub
                                                                6. Interaction with Documenter.jl
                                                                Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                                Literate.markdown:
                                                                • The default code fence will change from
                                                                  ```julia
 # code
 ```
                                                                  to Documenters @example blocks:
                                                                  ```@examples $(name)
 # code
-```
                                                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                  ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                Literate.notebook:
                                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                • Documenter style markdown math
                                                                  ```math
+```
                                                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                  ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                Literate.notebook:
                                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                • Documenter style markdown math
                                                                  ```math
 \int f dx
 ```
                                                                  is replaced with notebook compatible
                                                                  $$
 \int f dx
-$$
                                                                Literate.script:
                                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                
+$$

                                                              Literate.script:

                                                              • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                              \ No newline at end of file diff --git a/v2.2.0/fileformat/index.html b/v2.2.0/fileformat/index.html index 00acb7b..a58c0d2 100644 --- a/v2.2.0/fileformat/index.html +++ b/v2.2.0/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                              Edit on GitHub

                                                              2. File Format

                                                              The source file format for Literate 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.

                                                              2.1. Syntax

                                                              The basic syntax is simple:

                                                              • lines starting with # are treated as markdown,
                                                              • all other lines are treated as julia code.

                                                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                              Lets look at a simple example:

                                                              # # Rational numbers
+2. File Format · Literate.jl
                                                              Edit on GitHub
                                                              2. File Format
                                                              The source file format for Literate 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.
                                                              2.1. Syntax
                                                              The basic syntax is simple:
                                                              • lines starting with # are treated as markdown,
                                                              • all other lines are treated as julia code.
                                                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                              Lets look at a simple example:
                                                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                              For simple use this is all you need to know. The following additional special syntax can also be used:
                                                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                              2.2. Filtering Lines
                                                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                              • #md: line exclusive to markdown output,
                                                              • #nb: line exclusive to notebook output,
                                                              • #jl: line exclusive to script output,
                                                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                              Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                              Tip
                                                              The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                              #md # ```@docs
+z = x + y
                                                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                              For simple use this is all you need to know. The following additional special syntax can also be used:
                                                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                              2.2. Filtering Lines
                                                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                              • #md: line exclusive to markdown output,
                                                              • #nb: line exclusive to notebook output,
                                                              • #jl: line exclusive to script output,
                                                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                              Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                              Tip
                                                              The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                              #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                              The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                              using Test                      #src
-@test result == expected_result #src
                                                              2.3. Default Replacements
                                                              The following convenience "macros"/source placeholders are always expanded:
                                                              • @__NAME__:
                                                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                              • @__REPO_ROOT_URL__:
                                                                Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                              • @__NBVIEWER_ROOT_URL__:
                                                                Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                              • @__BINDER_ROOT_URL__:
                                                                Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                              
+@test result == expected_result #src

                                                              2.3. Default Replacements

                                                              The following convenience "macros"/source placeholders are always expanded:

                                                              • @__NAME__:

                                                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                              • @__REPO_ROOT_URL__:

                                                                Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                              • @__NBVIEWER_ROOT_URL__:

                                                                Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                              • @__BINDER_ROOT_URL__:

                                                                Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                              \ No newline at end of file diff --git a/v2.2.0/generated/example/index.html b/v2.2.0/generated/example/index.html index b834c32..eb4df42 100644 --- a/v2.2.0/generated/example/index.html +++ b/v2.2.0/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                                              Edit on GitHub

                                                              7. Example

                                                              This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                              Basic syntax

                                                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                              x = 1//3
-y = 2//5
                                                              2//5

                                                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                              • This line starts with #md and is thus only visible in the markdown output.

                                                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                              x + y
                                                              11//15
                                                              x * y
                                                              2//15

                                                              Output Capturing

                                                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                              Note

                                                              Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                              function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                                              Edit on GitHub
                                                              7. Example
                                                              This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                              Basic syntax
                                                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                              x = 1//3
+y = 2//5
                                                              2//5
                                                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                              • This line starts with #md and is thus only visible in the markdown output.
                                                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                              x + y
                                                              11//15
                                                              x * y
                                                              2//15
                                                              Output Capturing
                                                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                              Note
                                                              Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                              function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                                              4-element Array{Int64,1}:
  1
  2
  3
- 4
                                                              Just like in the REPL, outputs ending with a semicolon hides the output:
                                                              1 + 1;
                                                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                              using Plots
+ 4
                                                              Just like in the REPL, outputs ending with a semicolon hides the output:
                                                              1 + 1;
                                                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                              using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                              
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
-
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                                              Custom processing
                                                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                              z = 1.0 + 2.0im
                                                              1.0 + 2.0im
                                                              Documenter.jl interaction
                                                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                              This page was generated using Literate.jl.
                                                              
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                                              Custom processing
                                                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                              z = 1.0 + 2.0im
                                                              1.0 + 2.0im
                                                              Documenter.jl interaction
                                                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                              This page was generated using Literate.jl.
                                                              \ No newline at end of file diff --git a/v2.2.0/generated/name/index.html b/v2.2.0/generated/name/index.html index 4c00e83..1ef4bfc 100644 --- a/v2.2.0/generated/name/index.html +++ b/v2.2.0/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                              Edit on GitHub

                                                              Rational numbers

                                                              In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                              x = 1//3
                                                              1//3
                                                              y = 2//5
                                                              2//5

                                                              When adding x and y together we obtain a new rational number:

                                                              z = x + y
                                                              11//15
                                                              +Rational numbers · Literate.jl
                                                              Edit on GitHub

                                                              Rational numbers

                                                              In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                              x = 1//3
                                                              1//3
                                                              y = 2//5
                                                              2//5

                                                              When adding x and y together we obtain a new rational number:

                                                              z = x + y
                                                              11//15
                                                              \ No newline at end of file diff --git a/v2.2.0/index.html b/v2.2.0/index.html index 5e92e12..2b6513b 100644 --- a/v2.2.0/index.html +++ b/v2.2.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                              Edit on GitHub

                                                              1. Introduction

                                                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                              What?

                                                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                              The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                              Why?

                                                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                              It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                              +1. Introduction · Literate.jl
                                                              Edit on GitHub

                                                              1. Introduction

                                                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                              What?

                                                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                              The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                              Why?

                                                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                              It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                              \ No newline at end of file diff --git a/v2.2.0/outputformats/index.html b/v2.2.0/outputformats/index.html index efee599..0776322 100644 --- a/v2.2.0/outputformats/index.html +++ b/v2.2.0/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                              Edit on GitHub

                                                              4. Output Formats

                                                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                              # # Rational numbers
+4. Output Formats · Literate.jl
                                                              Edit on GitHub
                                                              4. Output Formats
                                                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                              and see how this is rendered in each of the output formats.
                                                              4.1. Markdown Output
                                                              Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                              ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.markdown.
                                                              Literate.markdown — Function
                                                              Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                              Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                              source
                                                              4.2. Notebook Output
                                                              Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                              Literate.notebook — Function
                                                              Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                              Generate a notebook from inputfile and write the result to outputdir.
                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                              source
                                                              Notebook metadata
                                                              Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                              %% optional ignored text [type] {optional metadata JSON}
                                                              Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                              4.3. Script Output
                                                              Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                              x = 1//3
+```
                                                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.markdown.
                                                              Literate.markdown — Function
                                                              Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                              Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                              source
                                                              4.2. Notebook Output
                                                              Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                              Literate.notebook — Function
                                                              Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                              Generate a notebook from inputfile and write the result to outputdir.
                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                              source
                                                              Notebook metadata
                                                              Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                              %% optional ignored text [type] {optional metadata JSON}
                                                              Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                              4.3. Script Output
                                                              Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                              x = 1//3
 
 y = 2//5
 
-z = x + y
                                                              We note that lines starting with # are removed and only the code lines have been kept.
                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                              Literate.script — Function
                                                              Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                              Generate a plain script file from inputfile and write the result to outputdir.
                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                              source
                                                              4.4. Configuration
                                                              The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                              Configuration precedence
                                                              Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                              Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                              Literate.DEFAULT_CONFIGURATION — Constant
                                                              DEFAULT_CONFIGURATION
                                                              Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                              Configuration keyDescriptionDefault valueComment
                                                              nameName of the output file (excluding file extension).filename(inputfile)
                                                              preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                              postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                              documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                              creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                              keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                              codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                              executeWhether to execute and capture the output.trueOnly applicable for Literate.notebook.
                                                              devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                              repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                              nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                              binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                              repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                              source
                                                              
+z = x + y

                                                              We note that lines starting with # are removed and only the code lines have been kept.

                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                              Literate.script — Function
                                                              Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)

                                                              Generate a plain script file from inputfile and write the result to outputdir.

                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                              source

                                                              4.4. Configuration

                                                              The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                              Configuration precedence

                                                              Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                              Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                              Literate.DEFAULT_CONFIGURATION — Constant
                                                              DEFAULT_CONFIGURATION

                                                              Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                              Configuration keyDescriptionDefault valueComment
                                                              nameName of the output file (excluding file extension).filename(inputfile)
                                                              preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                              postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                              documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                              creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                              keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                              codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                              executeWhether to execute and capture the output.trueOnly applicable for Literate.notebook.
                                                              devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                              repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                              nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                              binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                              repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                              source
                                                              \ No newline at end of file diff --git a/v2.2.0/pipeline/index.html b/v2.2.0/pipeline/index.html index 854e6b7..dcf75f0 100644 --- a/v2.2.0/pipeline/index.html +++ b/v2.2.0/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                              Edit on GitHub

                                                              3. Processing pipeline

                                                              The generation of output follows the same pipeline for all output formats:

                                                              1. Pre-processing
                                                              2. Parsing
                                                              3. Document generation
                                                              4. Post-processing
                                                              5. Writing to file

                                                              3.1. Pre-processing

                                                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                              3.2. Parsing

                                                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                              # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                              Edit on GitHub
                                                              3. Processing pipeline
                                                              The generation of output follows the same pipeline for all output formats:
                                                              1. Pre-processing
                                                              2. Parsing
                                                              3. Document generation
                                                              4. Post-processing
                                                              5. Writing to file
                                                              3.1. Pre-processing
                                                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                              3.2. Parsing
                                                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                              Chunk #2:
                                                              # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                              Chunk #3:
                                                              When adding `x` and `y` together we obtain a new rational number:
                                                              Chunk #4:
                                                              z = x + y
                                                              It is then up to the Document generation step to decide how these chunks should be treated.
                                                              Custom control over chunk splits
                                                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                              x = 1 // 3
+y = 2 // 5
                                                              Chunk #3:
                                                              When adding `x` and `y` together we obtain a new rational number:
                                                              Chunk #4:
                                                              z = x + y
                                                              It is then up to the Document generation step to decide how these chunks should be treated.
                                                              Custom control over chunk splits
                                                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                              x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                              The example above would result in two consecutive code-chunks.
                                                              Tip
                                                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                              It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                              3.3. Document generation
                                                              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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                              • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                              3.4. Post-processing
                                                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                              3.5. Writing to file
                                                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                              
+z = x + y

                                                              The example above would result in two consecutive code-chunks.

                                                              Tip

                                                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                              It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                              3.3. Document generation

                                                              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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                              • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                              3.4. Post-processing

                                                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                              3.5. Writing to file

                                                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                              \ No newline at end of file diff --git a/v2.2.0/search/index.html b/v2.2.0/search/index.html index 62e9727..67547a9 100644 --- a/v2.2.0/search/index.html +++ b/v2.2.0/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                              Loading search...

                                                                +Search · Literate.jl

                                                                Loading search...

                                                                  \ No newline at end of file diff --git a/v2.2.1/customprocessing/index.html b/v2.2.1/customprocessing/index.html index fc5cb58..7f0af9d 100644 --- a/v2.2.1/customprocessing/index.html +++ b/v2.2.1/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                                  Edit on GitHub

                                                                  5. Custom pre- and post-processing

                                                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                                  Example: Adding current date

                                                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                                  # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                                  Edit on GitHub
                                                                  5. Custom pre- and post-processing
                                                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                                  Example: Adding current date
                                                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                                  # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                                  where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                                  function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                  Example: Replacing include calls with included code
                                                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                  # # Replace includes
+end
                                                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                  Example: Replacing include calls with included code
                                                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                  # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                  function replace_includes(str)
+include("file2.jl")
                                                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                  function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                                  (of course replace included with your respective files)
                                                                  Finally, you simply pass this function to e.g. Literate.markdown as
                                                                  Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                                  This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                                  
+end

                                                                  (of course replace included with your respective files)

                                                                  Finally, you simply pass this function to e.g. Literate.markdown as

                                                                  Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                                  This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                                  \ No newline at end of file diff --git a/v2.2.1/documenter/index.html b/v2.2.1/documenter/index.html index 779f230..bb4680c 100644 --- a/v2.2.1/documenter/index.html +++ b/v2.2.1/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                                  Edit on GitHub

                                                                  6. Interaction with Documenter.jl

                                                                  Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                                                  Literate.markdown:

                                                                  • The default code fence will change from
                                                                    ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                    Edit on GitHub
                                                                    6. Interaction with Documenter.jl
                                                                    Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                                    Literate.markdown:
                                                                    • The default code fence will change from
                                                                      ```julia
 # code
 ```
                                                                      to Documenters @example blocks:
                                                                      ```@examples $(name)
 # code
-```
                                                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                      ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                    Literate.notebook:
                                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                    • Documenter style markdown math
                                                                      ```math
+```
                                                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                      ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                    Literate.notebook:
                                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                    • Documenter style markdown math
                                                                      ```math
 \int f dx
 ```
                                                                      is replaced with notebook compatible
                                                                      $$
 \int f dx
-$$
                                                                    Literate.script:
                                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                    
+$$

                                                                  Literate.script:

                                                                  • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                  \ No newline at end of file diff --git a/v2.2.1/fileformat/index.html b/v2.2.1/fileformat/index.html index 3dfaae2..a0c6308 100644 --- a/v2.2.1/fileformat/index.html +++ b/v2.2.1/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                                  Edit on GitHub

                                                                  2. File Format

                                                                  The source file format for Literate 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.

                                                                  2.1. Syntax

                                                                  The basic syntax is simple:

                                                                  • lines starting with # are treated as markdown,
                                                                  • all other lines are treated as julia code.

                                                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                                  Lets look at a simple example:

                                                                  # # Rational numbers
+2. File Format · Literate.jl
                                                                  Edit on GitHub
                                                                  2. File Format
                                                                  The source file format for Literate 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.
                                                                  2.1. Syntax
                                                                  The basic syntax is simple:
                                                                  • lines starting with # are treated as markdown,
                                                                  • all other lines are treated as julia code.
                                                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                                  Lets look at a simple example:
                                                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                  2.2. Filtering Lines
                                                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                  • #md: line exclusive to markdown output,
                                                                  • #nb: line exclusive to notebook output,
                                                                  • #jl: line exclusive to script output,
                                                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                  Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                                  Tip
                                                                  The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                  #md # ```@docs
+z = x + y
                                                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                  2.2. Filtering Lines
                                                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                  • #md: line exclusive to markdown output,
                                                                  • #nb: line exclusive to notebook output,
                                                                  • #jl: line exclusive to script output,
                                                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                  Lines starting with one of these tokens are filtered out in the preprocessing step.
                                                                  Tip
                                                                  The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                  #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                                  The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                                  using Test                      #src
-@test result == expected_result #src
                                                                  2.3. Default Replacements
                                                                  The following convenience "macros"/source placeholders are always expanded:
                                                                  • @__NAME__:
                                                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                                  • @__REPO_ROOT_URL__:
                                                                    Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                  • @__NBVIEWER_ROOT_URL__:
                                                                    Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                  • @__BINDER_ROOT_URL__:
                                                                    Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                    This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                  
+@test result == expected_result #src

                                                                  2.3. Default Replacements

                                                                  The following convenience "macros"/source placeholders are always expanded:

                                                                  • @__NAME__:

                                                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                                  • @__REPO_ROOT_URL__:

                                                                    Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                  • @__NBVIEWER_ROOT_URL__:

                                                                    Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                  • @__BINDER_ROOT_URL__:

                                                                    Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                    This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                  \ No newline at end of file diff --git a/v2.2.1/generated/example/index.html b/v2.2.1/generated/example/index.html index aebb500..a3975e7 100644 --- a/v2.2.1/generated/example/index.html +++ b/v2.2.1/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                                                  Edit on GitHub

                                                                  7. Example

                                                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                                  Basic syntax

                                                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                                  x = 1//3
-y = 2//5
                                                                  2//5

                                                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                                  • This line starts with #md and is thus only visible in the markdown output.

                                                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                                  x + y
                                                                  11//15
                                                                  x * y
                                                                  2//15

                                                                  Output Capturing

                                                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                                  Note

                                                                  Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                                  function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                                                  Edit on GitHub
                                                                  7. Example
                                                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                                  Basic syntax
                                                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                                  x = 1//3
+y = 2//5
                                                                  2//5
                                                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                                  • This line starts with #md and is thus only visible in the markdown output.
                                                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                                  x + y
                                                                  11//15
                                                                  x * y
                                                                  2//15
                                                                  Output Capturing
                                                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                                  Note
                                                                  Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                                  function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                                                  4-element Array{Int64,1}:
  1
  2
  3
- 4
                                                                  Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                  1 + 1;
                                                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                  using Plots
+ 4
                                                                  Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                  1 + 1;
                                                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                  using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                                  
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
-
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                                                  Custom processing
                                                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                                  z = 1.0 + 2.0im
                                                                  1.0 + 2.0im
                                                                  Documenter.jl interaction
                                                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                  This page was generated using Literate.jl.
                                                                  
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                                                  Custom processing
                                                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                                  z = 1.0 + 2.0im
                                                                  1.0 + 2.0im
                                                                  Documenter.jl interaction
                                                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                  This page was generated using Literate.jl.
                                                                  \ No newline at end of file diff --git a/v2.2.1/generated/name/index.html b/v2.2.1/generated/name/index.html index 0f84a0b..be314d4 100644 --- a/v2.2.1/generated/name/index.html +++ b/v2.2.1/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                                  Edit on GitHub

                                                                  Rational numbers

                                                                  In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                  x = 1//3
                                                                  1//3
                                                                  y = 2//5
                                                                  2//5

                                                                  When adding x and y together we obtain a new rational number:

                                                                  z = x + y
                                                                  11//15
                                                                  +Rational numbers · Literate.jl
                                                                  Edit on GitHub

                                                                  Rational numbers

                                                                  In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                  x = 1//3
                                                                  1//3
                                                                  y = 2//5
                                                                  2//5

                                                                  When adding x and y together we obtain a new rational number:

                                                                  z = x + y
                                                                  11//15
                                                                  \ No newline at end of file diff --git a/v2.2.1/index.html b/v2.2.1/index.html index 81be532..1ec1b32 100644 --- a/v2.2.1/index.html +++ b/v2.2.1/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                                  Edit on GitHub

                                                                  1. Introduction

                                                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                  What?

                                                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                  The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                                  Why?

                                                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                  +1. Introduction · Literate.jl
                                                                  Edit on GitHub

                                                                  1. Introduction

                                                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                  What?

                                                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                  The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                                  Why?

                                                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                  \ No newline at end of file diff --git a/v2.2.1/outputformats/index.html b/v2.2.1/outputformats/index.html index ee9c39b..1107e6f 100644 --- a/v2.2.1/outputformats/index.html +++ b/v2.2.1/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                                  Edit on GitHub

                                                                  4. Output Formats

                                                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                                  # # Rational numbers
+4. Output Formats · Literate.jl
                                                                  Edit on GitHub
                                                                  4. Output Formats
                                                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                                  and see how this is rendered in each of the output formats.
                                                                  4.1. Markdown Output
                                                                  Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                                  ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.markdown.
                                                                  Literate.markdown — Function
                                                                  Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                  Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                  source
                                                                  4.2. Notebook Output
                                                                  Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                  Literate.notebook — Function
                                                                  Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                  Generate a notebook from inputfile and write the result to outputdir.
                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                  source
                                                                  Notebook metadata
                                                                  Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                  %% optional ignored text [type] {optional metadata JSON}
                                                                  Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                  4.3. Script Output
                                                                  Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                  x = 1//3
+```
                                                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.markdown.
                                                                  Literate.markdown — Function
                                                                  Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                  Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                  source
                                                                  4.2. Notebook Output
                                                                  Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                  Literate.notebook — Function
                                                                  Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                  Generate a notebook from inputfile and write the result to outputdir.
                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                  source
                                                                  Notebook metadata
                                                                  Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                  %% optional ignored text [type] {optional metadata JSON}
                                                                  Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                  4.3. Script Output
                                                                  Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                  x = 1//3
 
 y = 2//5
 
-z = x + y
                                                                  We note that lines starting with # are removed and only the code lines have been kept.
                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                                  Literate.script — Function
                                                                  Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                  Generate a plain script file from inputfile and write the result to outputdir.
                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                  source
                                                                  4.4. Configuration
                                                                  The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                                  Configuration precedence
                                                                  Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                                  Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                                  Literate.DEFAULT_CONFIGURATION — Constant
                                                                  DEFAULT_CONFIGURATION
                                                                  Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                                  Configuration keyDescriptionDefault valueComment
                                                                  nameName of the output file (excluding file extension).filename(inputfile)
                                                                  preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                  postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                  documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                  creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                  keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                  codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                  executeWhether to execute and capture the output.trueOnly applicable for Literate.notebook.
                                                                  devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                  repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                  nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                  binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                  repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                  source
                                                                  
+z = x + y

                                                                  We note that lines starting with # are removed and only the code lines have been kept.

                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                                  Literate.script — Function
                                                                  Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)

                                                                  Generate a plain script file from inputfile and write the result to outputdir.

                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                                  source

                                                                  4.4. Configuration

                                                                  The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                                  Configuration precedence

                                                                  Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                                  Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                                  Literate.DEFAULT_CONFIGURATION — Constant
                                                                  DEFAULT_CONFIGURATION

                                                                  Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                                  Configuration keyDescriptionDefault valueComment
                                                                  nameName of the output file (excluding file extension).filename(inputfile)
                                                                  preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                  postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                  documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                  creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                  keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                  codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                  executeWhether to execute and capture the output.trueOnly applicable for Literate.notebook.
                                                                  devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                  repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                  nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                  binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                  repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                  source
                                                                  \ No newline at end of file diff --git a/v2.2.1/pipeline/index.html b/v2.2.1/pipeline/index.html index ccacef3..b41c2eb 100644 --- a/v2.2.1/pipeline/index.html +++ b/v2.2.1/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                                  Edit on GitHub

                                                                  3. Processing pipeline

                                                                  The generation of output follows the same pipeline for all output formats:

                                                                  1. Pre-processing
                                                                  2. Parsing
                                                                  3. Document generation
                                                                  4. Post-processing
                                                                  5. Writing to file

                                                                  3.1. Pre-processing

                                                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                                  3.2. Parsing

                                                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                                  # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                                  Edit on GitHub
                                                                  3. Processing pipeline
                                                                  The generation of output follows the same pipeline for all output formats:
                                                                  1. Pre-processing
                                                                  2. Parsing
                                                                  3. Document generation
                                                                  4. Post-processing
                                                                  5. Writing to file
                                                                  3.1. Pre-processing
                                                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                                  3.2. Parsing
                                                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                                  Chunk #2:
                                                                  # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                                  Chunk #3:
                                                                  When adding `x` and `y` together we obtain a new rational number:
                                                                  Chunk #4:
                                                                  z = x + y
                                                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                                                  Custom control over chunk splits
                                                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                  x = 1 // 3
+y = 2 // 5
                                                                  Chunk #3:
                                                                  When adding `x` and `y` together we obtain a new rational number:
                                                                  Chunk #4:
                                                                  z = x + y
                                                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                                                  Custom control over chunk splits
                                                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                  x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                                  The example above would result in two consecutive code-chunks.
                                                                  Tip
                                                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                                  It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                                  3.3. Document generation
                                                                  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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                                  3.4. Post-processing
                                                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                                  3.5. Writing to file
                                                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                                  
+z = x + y

                                                                  The example above would result in two consecutive code-chunks.

                                                                  Tip

                                                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                                  It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                                  3.3. Document generation

                                                                  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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                                  3.4. Post-processing

                                                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                                  3.5. Writing to file

                                                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                                  \ No newline at end of file diff --git a/v2.2.1/search/index.html b/v2.2.1/search/index.html index 3f3dd12..1bb22a8 100644 --- a/v2.2.1/search/index.html +++ b/v2.2.1/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                                  Loading search...

                                                                    +Search · Literate.jl

                                                                    Loading search...

                                                                      \ No newline at end of file diff --git a/v2.3.0/customprocessing/index.html b/v2.3.0/customprocessing/index.html index 7a28ac4..06cc8c3 100644 --- a/v2.3.0/customprocessing/index.html +++ b/v2.3.0/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                                      Edit on GitHub

                                                                      5. Custom pre- and post-processing

                                                                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                                      Example: Adding current date

                                                                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                                      # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                                      Edit on GitHub
                                                                      5. Custom pre- and post-processing
                                                                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                                      Example: Adding current date
                                                                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                                      # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                                      where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                                      function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                      Example: Replacing include calls with included code
                                                                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                      # # Replace includes
+end
                                                                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                      Example: Replacing include calls with included code
                                                                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                      # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                      function replace_includes(str)
+include("file2.jl")
                                                                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                      function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                                      (of course replace included with your respective files)
                                                                      Finally, you simply pass this function to e.g. Literate.markdown as
                                                                      Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                                      This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                                      
+end

                                                                      (of course replace included with your respective files)

                                                                      Finally, you simply pass this function to e.g. Literate.markdown as

                                                                      Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                                      This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                                      \ No newline at end of file diff --git a/v2.3.0/documenter/index.html b/v2.3.0/documenter/index.html index 26f8a8f..c195d64 100644 --- a/v2.3.0/documenter/index.html +++ b/v2.3.0/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                                      Edit on GitHub

                                                                      6. Interaction with Documenter.jl

                                                                      Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                                                      Literate.markdown:

                                                                      • The default code fence will change from
                                                                        ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                        Edit on GitHub
                                                                        6. Interaction with Documenter.jl
                                                                        Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                                        Literate.markdown:
                                                                        • The default code fence will change from
                                                                          ```julia
 # code
 ```
                                                                          to Documenters @example blocks:
                                                                          ```@examples $(name)
 # code
-```
                                                                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                          ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                        Literate.notebook:
                                                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                        • Documenter style markdown math
                                                                          ```math
+```
                                                                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                          ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                        Literate.notebook:
                                                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                        • Documenter style markdown math
                                                                          ```math
 \int f dx
 ```
                                                                          is replaced with notebook compatible
                                                                          $$
 \int f dx
-$$
                                                                        Literate.script:
                                                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                        
+$$

                                                                      Literate.script:

                                                                      • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                      \ No newline at end of file diff --git a/v2.3.0/fileformat/index.html b/v2.3.0/fileformat/index.html index 318e223..dbe703e 100644 --- a/v2.3.0/fileformat/index.html +++ b/v2.3.0/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                                      Edit on GitHub

                                                                      2. File Format

                                                                      The source file format for Literate 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.

                                                                      2.1. Syntax

                                                                      The basic syntax is simple:

                                                                      • lines starting with # are treated as markdown,
                                                                      • all other lines are treated as julia code.

                                                                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                                      Lets look at a simple example:

                                                                      # # Rational numbers
+2. File Format · Literate.jl
                                                                      Edit on GitHub
                                                                      2. File Format
                                                                      The source file format for Literate 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.
                                                                      2.1. Syntax
                                                                      The basic syntax is simple:
                                                                      • lines starting with # are treated as markdown,
                                                                      • all other lines are treated as julia code.
                                                                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                                      Lets look at a simple example:
                                                                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                      For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                      2.2. Filtering Lines
                                                                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                      • #md: line exclusive to markdown output,
                                                                      • #nb: line exclusive to notebook output,
                                                                      • #jl: line exclusive to script output,
                                                                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                      Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                      Tip
                                                                      The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                      #md # ```@docs
+z = x + y
                                                                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                      For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                      2.2. Filtering Lines
                                                                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                      • #md: line exclusive to markdown output,
                                                                      • #nb: line exclusive to notebook output,
                                                                      • #jl: line exclusive to script output,
                                                                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                      Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                      Tip
                                                                      The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                      #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                                      The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                                      using Test                      #src
-@test result == expected_result #src
                                                                      2.3. Default Replacements
                                                                      The following convenience "macros"/source placeholders are always expanded:
                                                                      • @__NAME__:
                                                                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                                      • @__REPO_ROOT_URL__:
                                                                        Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                      • @__NBVIEWER_ROOT_URL__:
                                                                        Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                      • @__BINDER_ROOT_URL__:
                                                                        Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                        [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                        This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                      
+@test result == expected_result #src

                                                                      2.3. Default Replacements

                                                                      The following convenience "macros"/source placeholders are always expanded:

                                                                      • @__NAME__:

                                                                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                                      • @__REPO_ROOT_URL__:

                                                                        Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                      • @__NBVIEWER_ROOT_URL__:

                                                                        Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                      • @__BINDER_ROOT_URL__:

                                                                        Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                        [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                        This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                      \ No newline at end of file diff --git a/v2.3.0/generated/example/index.html b/v2.3.0/generated/example/index.html index 776bbef..b928b44 100644 --- a/v2.3.0/generated/example/index.html +++ b/v2.3.0/generated/example/index.html @@ -1,7 +1,48 @@ - -7. Example · Literate.jl
                                                                      Edit on GitHub

                                                                      7. Example

                                                                      This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                                      Basic syntax

                                                                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                                      x = 1//3
-y = 2//5
                                                                      2//5

                                                                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                                      • This line starts with #md and is thus only visible in the markdown output.

                                                                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                                      x + y
                                                                      11//15
                                                                      x * y
                                                                      2//15

                                                                      Output Capturing

                                                                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                                      Note

                                                                      Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                                      function foo()
-    println("This string is printed to stdout.")
+7. Example · Literate.jl
                                                                      Edit on GitHub
                                                                      7. Example
                                                                      This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                                      Basic syntax
                                                                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                                      x = 1//3
+y = 2//5
                                                                      2//5
                                                                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                                      • This line starts with #md and is thus only visible in the markdown output.
                                                                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                                      x + y
                                                                      11//15
                                                                      x * y
                                                                      2//15
                                                                      Output Capturing
                                                                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                                      Note
                                                                      Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                                      function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                                                      4-element Array{Int64,1}:
  1
  2
  3
- 4
                                                                      Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                      1 + 1;
                                                                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                      using Plots
+ 4
                                                                      Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                      1 + 1;
                                                                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                      using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                                      
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
-
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                                                      Custom processing
                                                                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                                      z = 1.0 + 2.0im
                                                                      1.0 + 2.0im
                                                                      Documenter.jl interaction
                                                                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                      This page was generated using Literate.jl.
                                                                      
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                                                      Custom processing
                                                                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:
                                                                      z = 1.0 + 2.0im
                                                                      1.0 + 2.0im
                                                                      Documenter.jl interaction
                                                                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                      This page was generated using Literate.jl.
                                                                      \ No newline at end of file diff --git a/v2.3.0/generated/name/index.html b/v2.3.0/generated/name/index.html index 6f68aa8..cdf5715 100644 --- a/v2.3.0/generated/name/index.html +++ b/v2.3.0/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                                      Edit on GitHub

                                                                      Rational numbers

                                                                      In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                      x = 1//3
                                                                      1//3
                                                                      y = 2//5
                                                                      2//5

                                                                      When adding x and y together we obtain a new rational number:

                                                                      z = x + y
                                                                      11//15
                                                                      +Rational numbers · Literate.jl
                                                                      Edit on GitHub

                                                                      Rational numbers

                                                                      In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                      x = 1//3
                                                                      1//3
                                                                      y = 2//5
                                                                      2//5

                                                                      When adding x and y together we obtain a new rational number:

                                                                      z = x + y
                                                                      11//15
                                                                      \ No newline at end of file diff --git a/v2.3.0/index.html b/v2.3.0/index.html index 370cbfb..aee4c4f 100644 --- a/v2.3.0/index.html +++ b/v2.3.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                                      Edit on GitHub

                                                                      1. Introduction

                                                                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                      What?

                                                                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                                      Why?

                                                                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                      It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                      +1. Introduction · Literate.jl
                                                                      Edit on GitHub

                                                                      1. Introduction

                                                                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                      What?

                                                                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                      The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                                      Why?

                                                                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                      It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                      \ No newline at end of file diff --git a/v2.3.0/outputformats/index.html b/v2.3.0/outputformats/index.html index b6669e0..6463227 100644 --- a/v2.3.0/outputformats/index.html +++ b/v2.3.0/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                                      Edit on GitHub

                                                                      4. Output Formats

                                                                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                                      # # Rational numbers
+4. Output Formats · Literate.jl
                                                                      Edit on GitHub
                                                                      4. Output Formats
                                                                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                                      and see how this is rendered in each of the output formats.
                                                                      4.1. Markdown Output
                                                                      Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                                      ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.markdown.
                                                                      Literate.markdown — Function
                                                                      Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                      Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                      source
                                                                      4.2. Notebook Output
                                                                      Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                      Literate.notebook — Function
                                                                      Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                      Generate a notebook from inputfile and write the result to outputdir.
                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                      source
                                                                      Notebook metadata
                                                                      Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                      %% optional ignored text [type] {optional metadata JSON}
                                                                      Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                      4.3. Script Output
                                                                      Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                      x = 1//3
+```
                                                                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.markdown.
                                                                      Literate.markdown — Function
                                                                      Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                      Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                      source
                                                                      4.2. Notebook Output
                                                                      Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                      Literate.notebook — Function
                                                                      Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                      Generate a notebook from inputfile and write the result to outputdir.
                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                      source
                                                                      Notebook metadata
                                                                      Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                      %% optional ignored text [type] {optional metadata JSON}
                                                                      Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                      4.3. Script Output
                                                                      Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                      x = 1//3
 
 y = 2//5
 
-z = x + y
                                                                      We note that lines starting with # are removed and only the code lines have been kept.
                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                                      Literate.script — Function
                                                                      Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                      Generate a plain script file from inputfile and write the result to outputdir.
                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                      source
                                                                      4.4. Configuration
                                                                      The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                                      Configuration precedence
                                                                      Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                                      Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                                      Literate.DEFAULT_CONFIGURATION — Constant
                                                                      DEFAULT_CONFIGURATION
                                                                      Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                                      Configuration keyDescriptionDefault valueComment
                                                                      nameName of the output file (excluding file extension).filename(inputfile)
                                                                      preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                      postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                      documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                      creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                      keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                      codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                      executeWhether to execute and capture the output.trueOnly applicable for Literate.notebook.
                                                                      devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                      repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                      nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                      binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                      repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                      source
                                                                      
+z = x + y

                                                                      We note that lines starting with # are removed and only the code lines have been kept.

                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                                      Literate.script — Function
                                                                      Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)

                                                                      Generate a plain script file from inputfile and write the result to outputdir.

                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                                      source

                                                                      4.4. Configuration

                                                                      The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                                      Configuration precedence

                                                                      Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                                      Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                                      Literate.DEFAULT_CONFIGURATION — Constant
                                                                      DEFAULT_CONFIGURATION

                                                                      Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                                      Configuration keyDescriptionDefault valueComment
                                                                      nameName of the output file (excluding file extension).filename(inputfile)
                                                                      preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                      postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                      documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                      creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                      keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                      codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                      executeWhether to execute and capture the output.trueOnly applicable for Literate.notebook.
                                                                      devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                      repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                      nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                      binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                      repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                      source
                                                                      \ No newline at end of file diff --git a/v2.3.0/pipeline/index.html b/v2.3.0/pipeline/index.html index 23c6478..3e31984 100644 --- a/v2.3.0/pipeline/index.html +++ b/v2.3.0/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                                      Edit on GitHub

                                                                      3. Processing pipeline

                                                                      The generation of output follows the same pipeline for all output formats:

                                                                      1. Pre-processing
                                                                      2. Parsing
                                                                      3. Document generation
                                                                      4. Post-processing
                                                                      5. Writing to file

                                                                      3.1. Pre-processing

                                                                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                                      3.2. Parsing

                                                                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                                      # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                                      Edit on GitHub
                                                                      3. Processing pipeline
                                                                      The generation of output follows the same pipeline for all output formats:
                                                                      1. Pre-processing
                                                                      2. Parsing
                                                                      3. Document generation
                                                                      4. Post-processing
                                                                      5. Writing to file
                                                                      3.1. Pre-processing
                                                                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                                      3.2. Parsing
                                                                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                                      Chunk #2:
                                                                      # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                                      Chunk #3:
                                                                      When adding `x` and `y` together we obtain a new rational number:
                                                                      Chunk #4:
                                                                      z = x + y
                                                                      It is then up to the Document generation step to decide how these chunks should be treated.
                                                                      Custom control over chunk splits
                                                                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                      x = 1 // 3
+y = 2 // 5
                                                                      Chunk #3:
                                                                      When adding `x` and `y` together we obtain a new rational number:
                                                                      Chunk #4:
                                                                      z = x + y
                                                                      It is then up to the Document generation step to decide how these chunks should be treated.
                                                                      Custom control over chunk splits
                                                                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                      x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                                      The example above would result in two consecutive code-chunks.
                                                                      Tip
                                                                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                                      It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                                      3.3. Document generation
                                                                      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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                      • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                                      3.4. Post-processing
                                                                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                                      3.5. Writing to file
                                                                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                                      
+z = x + y

                                                                      The example above would result in two consecutive code-chunks.

                                                                      Tip

                                                                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                                      It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                                      3.3. Document generation

                                                                      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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                      • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                                      3.4. Post-processing

                                                                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                                      3.5. Writing to file

                                                                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                                      \ No newline at end of file diff --git a/v2.3.0/search/index.html b/v2.3.0/search/index.html index ad10d0a..ab3641f 100644 --- a/v2.3.0/search/index.html +++ b/v2.3.0/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                                      Loading search...

                                                                        +Search · Literate.jl

                                                                        Loading search...

                                                                          \ No newline at end of file diff --git a/v2.3.1/customprocessing/index.html b/v2.3.1/customprocessing/index.html index 801543b..00ede74 100644 --- a/v2.3.1/customprocessing/index.html +++ b/v2.3.1/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                                          Edit on GitHub

                                                                          5. Custom pre- and post-processing

                                                                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                                          Example: Adding current date

                                                                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                                          # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                                          Edit on GitHub
                                                                          5. Custom pre- and post-processing
                                                                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                                          Example: Adding current date
                                                                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                                          # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                                          where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                                          function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                          Example: Replacing include calls with included code
                                                                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                          # # Replace includes
+end
                                                                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                          Example: Replacing include calls with included code
                                                                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                          # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                          function replace_includes(str)
+include("file2.jl")
                                                                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                          function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                                          (of course replace included with your respective files)
                                                                          Finally, you simply pass this function to e.g. Literate.markdown as
                                                                          Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                                          This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                                          
+end

                                                                          (of course replace included with your respective files)

                                                                          Finally, you simply pass this function to e.g. Literate.markdown as

                                                                          Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                                          This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                                          \ No newline at end of file diff --git a/v2.3.1/documenter/index.html b/v2.3.1/documenter/index.html index b0325b3..5bfddb8 100644 --- a/v2.3.1/documenter/index.html +++ b/v2.3.1/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                                          Edit on GitHub

                                                                          6. Interaction with Documenter.jl

                                                                          Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                                                          Literate.markdown:

                                                                          • The default code fence will change from
                                                                            ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                            Edit on GitHub
                                                                            6. Interaction with Documenter.jl
                                                                            Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                                            Literate.markdown:
                                                                            • The default code fence will change from
                                                                              ```julia
 # code
 ```
                                                                              to Documenters @example blocks:
                                                                              ```@examples $(name)
 # code
-```
                                                                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                              ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                            Literate.notebook:
                                                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                            • Documenter style markdown math
                                                                              ```math
+```
                                                                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                              ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                            Literate.notebook:
                                                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                            • Documenter style markdown math
                                                                              ```math
 \int f dx
 ```
                                                                              is replaced with notebook compatible
                                                                              $$
 \int f dx
-$$
                                                                            Literate.script:
                                                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                            
+$$

                                                                          Literate.script:

                                                                          • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                          \ No newline at end of file diff --git a/v2.3.1/fileformat/index.html b/v2.3.1/fileformat/index.html index 80be548..61b59b7 100644 --- a/v2.3.1/fileformat/index.html +++ b/v2.3.1/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                                          Edit on GitHub

                                                                          2. File Format

                                                                          The source file format for Literate 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.

                                                                          2.1. Syntax

                                                                          The basic syntax is simple:

                                                                          • lines starting with # are treated as markdown,
                                                                          • all other lines are treated as julia code.

                                                                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                                          Lets look at a simple example:

                                                                          # # Rational numbers
+2. File Format · Literate.jl
                                                                          Edit on GitHub
                                                                          2. File Format
                                                                          The source file format for Literate 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.
                                                                          2.1. Syntax
                                                                          The basic syntax is simple:
                                                                          • lines starting with # are treated as markdown,
                                                                          • all other lines are treated as julia code.
                                                                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                                          Lets look at a simple example:
                                                                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                          For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                          2.2. Filtering Lines
                                                                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                          • #md: line exclusive to markdown output,
                                                                          • #nb: line exclusive to notebook output,
                                                                          • #jl: line exclusive to script output,
                                                                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                          Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                          Tip
                                                                          The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                          #md # ```@docs
+z = x + y
                                                                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                          For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                          2.2. Filtering Lines
                                                                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                          • #md: line exclusive to markdown output,
                                                                          • #nb: line exclusive to notebook output,
                                                                          • #jl: line exclusive to script output,
                                                                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                          Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                          Tip
                                                                          The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                          #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                                          The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                                          using Test                      #src
-@test result == expected_result #src
                                                                          2.3. Default Replacements
                                                                          The following convenience "macros"/source placeholders are always expanded:
                                                                          • @__NAME__:
                                                                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                                          • @__REPO_ROOT_URL__:
                                                                            Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                          • @__NBVIEWER_ROOT_URL__:
                                                                            Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                          • @__BINDER_ROOT_URL__:
                                                                            Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                            [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                            This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                          
+@test result == expected_result #src

                                                                          2.3. Default Replacements

                                                                          The following convenience "macros"/source placeholders are always expanded:

                                                                          • @__NAME__:

                                                                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                                          • @__REPO_ROOT_URL__:

                                                                            Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                          • @__NBVIEWER_ROOT_URL__:

                                                                            Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                          • @__BINDER_ROOT_URL__:

                                                                            Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                            [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                            This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                          \ No newline at end of file diff --git a/v2.3.1/generated/example/index.html b/v2.3.1/generated/example/index.html index a5d9c6b..fa23a35 100644 --- a/v2.3.1/generated/example/index.html +++ b/v2.3.1/generated/example/index.html @@ -1,7 +1,48 @@ - -8. Example · Literate.jl
                                                                          Edit on GitHub

                                                                          8. Example

                                                                          This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                                          Basic syntax

                                                                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                                          x = 1//3
-y = 2//5
                                                                          2//5

                                                                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                                          • This line starts with #md and is thus only visible in the markdown output.

                                                                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                                          x + y
                                                                          11//15
                                                                          x * y
                                                                          2//15

                                                                          Output Capturing

                                                                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                                          Note

                                                                          Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                                          function foo()
-    println("This string is printed to stdout.")
+8. Example · Literate.jl
                                                                          Edit on GitHub
                                                                          8. Example
                                                                          This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                                          Basic syntax
                                                                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                                          x = 1//3
+y = 2//5
                                                                          2//5
                                                                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                                          • This line starts with #md and is thus only visible in the markdown output.
                                                                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                                          x + y
                                                                          11//15
                                                                          x * y
                                                                          2//15
                                                                          Output Capturing
                                                                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                                          Note
                                                                          Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                                          function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,121 +50,55 @@ foo()
                                                                          4-element Array{Int64,1}:
  1
  2
  3
- 4
                                                                          Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                          1 + 1;
                                                                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                          using Plots
+ 4
                                                                          Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                          1 + 1;
                                                                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                          using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                                          
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-0
-
-
-5
-
-
-10
-
-
-15
-
-
--1.0
-
-
--0.5
-
-
-0.0
-
-
-0.5
-
-
-1.0
-
-051015-1.0-0.50.00.51.0
-
-
-
-
-
-y1
-
-y1
-
-y2
-
-
-
                                                                          Custom processing
                                                                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                          x = 123
                                                                          123
                                                                          In this case the preprocessing function is defined by
                                                                          function pre(s::String)
-    s = replace(s, "x = 123" => "y = 321")
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">y2
                                                                          Custom processing
                                                                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                          x = 123
                                                                          123
                                                                          In this case the preprocessing function is defined by
                                                                          function pre(s::String)
+    s = replace(s, "x = 123" => "y = 321")
     return s
-end
                                                                          pre (generic function with 1 method)
                                                                          Documenter.jl interaction
                                                                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                          This page was generated using Literate.jl.
                                                                          
+end
                                                                          pre (generic function with 1 method)

                                                                          Documenter.jl interaction

                                                                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                                                                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                                                                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                                                                          This page was generated using Literate.jl.

                                                                          \ No newline at end of file diff --git a/v2.3.1/generated/name/index.html b/v2.3.1/generated/name/index.html index eb30ba7..5fa9789 100644 --- a/v2.3.1/generated/name/index.html +++ b/v2.3.1/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                                          Edit on GitHub

                                                                          Rational numbers

                                                                          In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                          x = 1//3
                                                                          1//3
                                                                          y = 2//5
                                                                          2//5

                                                                          When adding x and y together we obtain a new rational number:

                                                                          z = x + y
                                                                          11//15
                                                                          +Rational numbers · Literate.jl
                                                                          Edit on GitHub

                                                                          Rational numbers

                                                                          In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                          x = 1//3
                                                                          1//3
                                                                          y = 2//5
                                                                          2//5

                                                                          When adding x and y together we obtain a new rational number:

                                                                          z = x + y
                                                                          11//15
                                                                          \ No newline at end of file diff --git a/v2.3.1/index.html b/v2.3.1/index.html index 15403cd..b3abf76 100644 --- a/v2.3.1/index.html +++ b/v2.3.1/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                                          Edit on GitHub

                                                                          1. Introduction

                                                                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                          What?

                                                                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                                          Why?

                                                                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                          It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                          +1. Introduction · Literate.jl
                                                                          Edit on GitHub

                                                                          1. Introduction

                                                                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                          What?

                                                                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                          The public interface consists mainly of three functions, all of which take the same script file as input, but generate different output:

                                                                          Why?

                                                                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                          It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                          \ No newline at end of file diff --git a/v2.3.1/outputformats/index.html b/v2.3.1/outputformats/index.html index 0b8743d..40ee0a4 100644 --- a/v2.3.1/outputformats/index.html +++ b/v2.3.1/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                                          Edit on GitHub

                                                                          4. Output Formats

                                                                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                                          # # Rational numbers
+4. Output Formats · Literate.jl
                                                                          Edit on GitHub
                                                                          4. Output Formats
                                                                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                                          and see how this is rendered in each of the output formats.
                                                                          4.1. Markdown Output
                                                                          Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                                          ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,8 +72,8 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.markdown.
                                                                          Literate.markdown — Function
                                                                          Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                          Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                          source
                                                                          4.2. Notebook Output
                                                                          Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                          Literate.notebook — Function
                                                                          Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                          Generate a notebook from inputfile and write the result to outputdir.
                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                          source
                                                                          Notebook metadata
                                                                          Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                          %% optional ignored text [type] {optional metadata JSON}
                                                                          Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                          4.3. Script Output
                                                                          Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                          x = 1//3
+```
                                                                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.markdown.
                                                                          Literate.markdown — Function
                                                                          Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                          Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                          source
                                                                          4.2. Notebook Output
                                                                          Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                          Literate.notebook — Function
                                                                          Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                          Generate a notebook from inputfile and write the result to outputdir.
                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                          source
                                                                          Notebook metadata
                                                                          Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                          %% optional ignored text [type] {optional metadata JSON}
                                                                          Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                          4.3. Script Output
                                                                          Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                          x = 1//3
 
 y = 2//5
 
-z = x + y
                                                                          We note that lines starting with # are removed and only the code lines have been kept.
                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                                          Literate.script — Function
                                                                          Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                          Generate a plain script file from inputfile and write the result to outputdir.
                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                          source
                                                                          4.4. Configuration
                                                                          The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                                          Configuration precedence
                                                                          Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                                          Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                                          Literate.DEFAULT_CONFIGURATION — Constant
                                                                          DEFAULT_CONFIGURATION
                                                                          Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                                          Configuration keyDescriptionDefault valueComment
                                                                          nameName of the output file (excluding file extension).filename(inputfile)
                                                                          preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                          postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                          documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                          creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                          keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                          codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                          executeWhether to execute and capture the output.trueOnly applicable for Literate.notebook.
                                                                          devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                          repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                          nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                          binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                          repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                          source
                                                                          
+z = x + y

                                                                          We note that lines starting with # are removed and only the code lines have been kept.

                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                                          Literate.script — Function
                                                                          Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)

                                                                          Generate a plain script file from inputfile and write the result to outputdir.

                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                                          source

                                                                          4.4. Configuration

                                                                          The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                                          Configuration precedence

                                                                          Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                                          Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                                          Literate.DEFAULT_CONFIGURATION — Constant
                                                                          DEFAULT_CONFIGURATION

                                                                          Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                                          Configuration keyDescriptionDefault valueComment
                                                                          nameName of the output file (excluding file extension).filename(inputfile)
                                                                          preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                          postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                          documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                          creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                          keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                          codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                          executeWhether to execute and capture the output.trueOnly applicable for Literate.notebook.
                                                                          devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                          repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                          nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                          binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                          repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                          source
                                                                          \ No newline at end of file diff --git a/v2.3.1/pipeline/index.html b/v2.3.1/pipeline/index.html index 9a6956f..a61c42f 100644 --- a/v2.3.1/pipeline/index.html +++ b/v2.3.1/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                                          Edit on GitHub

                                                                          3. Processing pipeline

                                                                          The generation of output follows the same pipeline for all output formats:

                                                                          1. Pre-processing
                                                                          2. Parsing
                                                                          3. Document generation
                                                                          4. Post-processing
                                                                          5. Writing to file

                                                                          3.1. Pre-processing

                                                                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                                          3.2. Parsing

                                                                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                                          # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                                          Edit on GitHub
                                                                          3. Processing pipeline
                                                                          The generation of output follows the same pipeline for all output formats:
                                                                          1. Pre-processing
                                                                          2. Parsing
                                                                          3. Document generation
                                                                          4. Post-processing
                                                                          5. Writing to file
                                                                          3.1. Pre-processing
                                                                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                                          3.2. Parsing
                                                                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                                          Chunk #2:
                                                                          # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                                          Chunk #3:
                                                                          When adding `x` and `y` together we obtain a new rational number:
                                                                          Chunk #4:
                                                                          z = x + y
                                                                          It is then up to the Document generation step to decide how these chunks should be treated.
                                                                          Custom control over chunk splits
                                                                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                          x = 1 // 3
+y = 2 // 5
                                                                          Chunk #3:
                                                                          When adding `x` and `y` together we obtain a new rational number:
                                                                          Chunk #4:
                                                                          z = x + y
                                                                          It is then up to the Document generation step to decide how these chunks should be treated.
                                                                          Custom control over chunk splits
                                                                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                          x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                                          The example above would result in two consecutive code-chunks.
                                                                          Tip
                                                                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                                          It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                                          3.3. Document generation
                                                                          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, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                          • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                                          3.4. Post-processing
                                                                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                                          3.5. Writing to file
                                                                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                                          
+z = x + y

                                                                          The example above would result in two consecutive code-chunks.

                                                                          Tip

                                                                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                                          It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                                          3.3. Document generation

                                                                          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, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                          • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                                          3.4. Post-processing

                                                                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                                          3.5. Writing to file

                                                                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                                          \ No newline at end of file diff --git a/v2.3.1/search/index.html b/v2.3.1/search/index.html index 4902759..b6cc78b 100644 --- a/v2.3.1/search/index.html +++ b/v2.3.1/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                                          Loading search...

                                                                            +Search · Literate.jl

                                                                            Loading search...

                                                                              \ No newline at end of file diff --git a/v2.3.1/tips/index.html b/v2.3.1/tips/index.html index 2c7978d..721d869 100644 --- a/v2.3.1/tips/index.html +++ b/v2.3.1/tips/index.html @@ -1,5 +1,46 @@ - -7. Tips and Tricks · Literate.jl
                                                                              Edit on GitHub

                                                                              7. Tips and Tricks

                                                                              This section lists some tips and tricks that might be useful for using Literate.

                                                                              Filesize of generated notebooks

                                                                              When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.

                                                                              A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.

                                                                              In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" and image to be captures as image/png only, you can use

                                                                              import DisplayAs
+7. Tips and Tricks · Literate.jl
                                                                              Edit on GitHub
                                                                              7. Tips and Tricks
                                                                              This section lists some tips and tricks that might be useful for using Literate.
                                                                              Filesize of generated notebooks
                                                                              When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.
                                                                              A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.
                                                                              In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" and image to be captures as image/png only, you can use
                                                                              import DisplayAs
 img = plot(...)
 img = DisplayAs.PNG(img)
                                                                              This can save some memory, since the image is never captured in e.g. SVG or HTML formats.
                                                                              Note
                                                                              It is best to always let the object be showable as text/plain. This can be achieved by nested calls to DisplayAs output types. For example, to limit an image img to be showable as just image/png and text/plain you can use
                                                                              img = plot(...)
-img = DisplayAs.Text(DisplayAs.Text(img))
                                                                              
+img = DisplayAs.Text(DisplayAs.Text(img))
                                                                              \ No newline at end of file diff --git a/v2.4.0/customprocessing/index.html b/v2.4.0/customprocessing/index.html index 04517bb..7894434 100644 --- a/v2.4.0/customprocessing/index.html +++ b/v2.4.0/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                                              Edit on GitHub

                                                                              5. Custom pre- and post-processing

                                                                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                                              Example: Adding current date

                                                                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                                              # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                                              Edit on GitHub
                                                                              5. Custom pre- and post-processing
                                                                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                                              Example: Adding current date
                                                                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                                              # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                                              where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                                              function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                              Example: Replacing include calls with included code
                                                                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                              # # Replace includes
+end
                                                                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                              Example: Replacing include calls with included code
                                                                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                              # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                              function replace_includes(str)
+include("file2.jl")
                                                                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                              function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                                              (of course replace included with your respective files)
                                                                              Finally, you simply pass this function to e.g. Literate.markdown as
                                                                              Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                                              This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                                              
+end

                                                                              (of course replace included with your respective files)

                                                                              Finally, you simply pass this function to e.g. Literate.markdown as

                                                                              Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                                              This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                                              \ No newline at end of file diff --git a/v2.4.0/documenter/index.html b/v2.4.0/documenter/index.html index d0ef534..33f1515 100644 --- a/v2.4.0/documenter/index.html +++ b/v2.4.0/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                                              Edit on GitHub

                                                                              6. Interaction with Documenter.jl

                                                                              Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                                                              Literate.markdown:

                                                                              • The default code fence will change from
                                                                                ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                                Edit on GitHub
                                                                                6. Interaction with Documenter.jl
                                                                                Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                                                Literate.markdown:
                                                                                • The default code fence will change from
                                                                                  ```julia
 # code
 ```
                                                                                  to Documenters @example blocks:
                                                                                  ```@examples $(name)
 # code
-```
                                                                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                  ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                                Literate.notebook:
                                                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                • Documenter style markdown math
                                                                                  ```math
+```
                                                                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                  ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                                Literate.notebook:
                                                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                • Documenter style markdown math
                                                                                  ```math
 \int f dx
 ```
                                                                                  is replaced with notebook compatible
                                                                                  $$
 \int f dx
-$$
                                                                                Literate.script:
                                                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                
+$$

                                                                              Literate.script:

                                                                              • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                              \ No newline at end of file diff --git a/v2.4.0/fileformat/index.html b/v2.4.0/fileformat/index.html index c1f7ec5..ff49acd 100644 --- a/v2.4.0/fileformat/index.html +++ b/v2.4.0/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                                              Edit on GitHub

                                                                              2. File Format

                                                                              The source file format for Literate 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.

                                                                              2.1. Syntax

                                                                              The basic syntax is simple:

                                                                              • lines starting with # are treated as markdown,
                                                                              • all other lines are treated as julia code.

                                                                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                                              Lets look at a simple example:

                                                                              # # Rational numbers
+2. File Format · Literate.jl
                                                                              Edit on GitHub
                                                                              2. File Format
                                                                              The source file format for Literate 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.
                                                                              2.1. Syntax
                                                                              The basic syntax is simple:
                                                                              • lines starting with # are treated as markdown,
                                                                              • all other lines are treated as julia code.
                                                                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                                              Lets look at a simple example:
                                                                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                              For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                              2.2. Filtering Lines
                                                                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                              • #md: line exclusive to markdown output,
                                                                              • #nb: line exclusive to notebook output,
                                                                              • #jl: line exclusive to script output,
                                                                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                              Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                              Literate 2.3
                                                                              Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                              Tip
                                                                              The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                              #md # ```@docs
+z = x + y
                                                                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                              For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                              2.2. Filtering Lines
                                                                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                              • #md: line exclusive to markdown output,
                                                                              • #nb: line exclusive to notebook output,
                                                                              • #jl: line exclusive to script output,
                                                                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                              Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                              Literate 2.3
                                                                              Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                              Tip
                                                                              The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                              #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                                              The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                                              using Test                      #src
-@test result == expected_result #src
                                                                              2.3. Default Replacements
                                                                              The following convenience "macros"/source placeholders are always expanded:
                                                                              • @__NAME__:
                                                                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                                              • @__REPO_ROOT_URL__:
                                                                                Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                              • @__NBVIEWER_ROOT_URL__:
                                                                                Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                              • @__BINDER_ROOT_URL__:
                                                                                Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                                [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                                This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                              Literate 2.1
                                                                              GitHub Actions support for the macros above requires at least Literate version 2.1.
                                                                              Literate 2.2
                                                                              GitLab CI support for the macros above requires at least Literate version 2.2.
                                                                              
+@test result == expected_result #src

                                                                              2.3. Default Replacements

                                                                              The following convenience "macros"/source placeholders are always expanded:

                                                                              • @__NAME__:

                                                                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                                              • @__REPO_ROOT_URL__:

                                                                                Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                              • @__NBVIEWER_ROOT_URL__:

                                                                                Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                              • @__BINDER_ROOT_URL__:

                                                                                Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                                [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                                This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                              Literate 2.1

                                                                              GitHub Actions support for the macros above requires at least Literate version 2.1.

                                                                              Literate 2.2

                                                                              GitLab CI support for the macros above requires at least Literate version 2.2.

                                                                              \ No newline at end of file diff --git a/v2.4.0/generated/example/index.html b/v2.4.0/generated/example/index.html index 2dfff8b..f1dddb6 100644 --- a/v2.4.0/generated/example/index.html +++ b/v2.4.0/generated/example/index.html @@ -1,7 +1,48 @@ - -8. Example · Literate.jl
                                                                              Edit on GitHub

                                                                              8. Example

                                                                              This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                                              Basic syntax

                                                                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                                              x = 1//3
-y = 2//5
                                                                              2//5

                                                                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                                              • This line starts with #md and is thus only visible in the markdown output.

                                                                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                                              x + y
                                                                              11//15
                                                                              x * y
                                                                              2//15

                                                                              Output Capturing

                                                                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                                              Note

                                                                              Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                                              function foo()
-    println("This string is printed to stdout.")
+8. Example · Literate.jl
                                                                              Edit on GitHub
                                                                              8. Example
                                                                              This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                                              Basic syntax
                                                                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                                              x = 1//3
+y = 2//5
                                                                              2//5
                                                                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                                              • This line starts with #md and is thus only visible in the markdown output.
                                                                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                                              x + y
                                                                              11//15
                                                                              x * y
                                                                              2//15
                                                                              Output Capturing
                                                                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                                              Note
                                                                              Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                                              function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,94 +50,55 @@ foo()
                                                                              4-element Array{Int64,1}:
  1
  2
  3
- 4
                                                                              Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                              1 + 1;
                                                                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                              using Plots
+ 4
                                                                              Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                              1 + 1;
                                                                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                              using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                                              
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
                                                                              Custom processing
                                                                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                              x = 123
                                                                              123
                                                                              In this case the preprocessing function is defined by
                                                                              function pre(s::String)
-    s = replace(s, "x = 123" => "y = 321")
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">
                                                                              Custom processing
                                                                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                              x = 123
                                                                              123
                                                                              In this case the preprocessing function is defined by
                                                                              function pre(s::String)
+    s = replace(s, "x = 123" => "y = 321")
     return s
-end
                                                                              pre (generic function with 1 method)
                                                                              Documenter.jl interaction
                                                                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                              This page was generated using Literate.jl.
                                                                              
+end
                                                                              pre (generic function with 1 method)

                                                                              Documenter.jl interaction

                                                                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                                                                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                                                                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                                                                              This page was generated using Literate.jl.

                                                                              \ No newline at end of file diff --git a/v2.4.0/generated/name/index.html b/v2.4.0/generated/name/index.html index 15c22b9..769f4dd 100644 --- a/v2.4.0/generated/name/index.html +++ b/v2.4.0/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                                              Edit on GitHub

                                                                              Rational numbers

                                                                              In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                              x = 1//3
                                                                              1//3
                                                                              y = 2//5
                                                                              2//5

                                                                              When adding x and y together we obtain a new rational number:

                                                                              z = x + y
                                                                              11//15
                                                                              +Rational numbers · Literate.jl
                                                                              Edit on GitHub

                                                                              Rational numbers

                                                                              In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                              x = 1//3
                                                                              1//3
                                                                              y = 2//5
                                                                              2//5

                                                                              When adding x and y together we obtain a new rational number:

                                                                              z = x + y
                                                                              11//15
                                                                              \ No newline at end of file diff --git a/v2.4.0/index.html b/v2.4.0/index.html index 17b4fef..164183b 100644 --- a/v2.4.0/index.html +++ b/v2.4.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                                              Edit on GitHub

                                                                              1. Introduction

                                                                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                              What?

                                                                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                              The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                              • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                              • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                              • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                              Why?

                                                                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                              It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                              +1. Introduction · Literate.jl
                                                                              Edit on GitHub

                                                                              1. Introduction

                                                                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                              What?

                                                                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                              The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                              • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                              • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                              • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                              Why?

                                                                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                              It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                              \ No newline at end of file diff --git a/v2.4.0/outputformats/index.html b/v2.4.0/outputformats/index.html index d7a781c..a13c787 100644 --- a/v2.4.0/outputformats/index.html +++ b/v2.4.0/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                                              Edit on GitHub

                                                                              4. Output Formats

                                                                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                                              # # Rational numbers
+4. Output Formats · Literate.jl
                                                                              Edit on GitHub
                                                                              4. Output Formats
                                                                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                                              and see how this is rendered in each of the output formats.
                                                                              4.1. Markdown Output
                                                                              Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                                              ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,23 +72,23 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                              It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                              ```julia
+```
                                                                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                              It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                              ```julia
 x = 1//3
 ```
 ```
 1//3
-```
                                                                              In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                              Note
                                                                              Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                              Literate 2.4
                                                                              Code execution of markdown output requires at least Literate version 2.4.
                                                                              See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                              Literate.markdown — Function
                                                                              Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                              Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                              source
                                                                              4.2. Notebook Output
                                                                              Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                              Literate.notebook — Function
                                                                              Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                              Generate a notebook from inputfile and write the result to outputdir.
                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                              source
                                                                              Notebook metadata
                                                                              Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                              %% optional ignored text [type] {optional metadata JSON}
                                                                              Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                              The following would create a 3 slide deck with RISE:
                                                                              #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
+```
                                                                              In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                              Note
                                                                              Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                              Literate 2.4
                                                                              Code execution of markdown output requires at least Literate version 2.4.
                                                                              See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                              Literate.markdown — Function
                                                                              Literate.markdown(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                              Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                              source
                                                                              4.2. Notebook Output
                                                                              Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                              Literate.notebook — Function
                                                                              Literate.notebook(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                              Generate a notebook from inputfile and write the result to outputdir.
                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                              source
                                                                              Notebook metadata
                                                                              Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                              %% optional ignored text [type] {optional metadata JSON}
                                                                              Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                              The following would create a 3 slide deck with RISE:
                                                                              #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
 # # Some title
 #
-# We're using `#nb` so the metadata is only included in notebook output
+# We're using `#nb` so the metadata is only included in notebook output
 
-#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
+#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
 x = 1//3
 y = 2//5
 
-#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
+#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
 # For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)
                                                                              4.3. Script Output
                                                                              Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                              x = 1//3
 
 y = 2//5
 
-z = x + y
                                                                              We note that lines starting with # are removed and only the code lines have been kept.
                                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                                              Literate.script — Function
                                                                              Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)
                                                                              Generate a plain script file from inputfile and write the result to outputdir.
                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                              source
                                                                              4.4. Configuration
                                                                              The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                                              Literate 2.2
                                                                              Passing configuration as a dictionary requires at least Literate version 2.2.
                                                                              Configuration precedence
                                                                              Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                                              Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                                              Literate.DEFAULT_CONFIGURATION — Constant
                                                                              DEFAULT_CONFIGURATION
                                                                              Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                                              Configuration keyDescriptionDefault valueComment
                                                                              nameName of the output file (excluding file extension).filename(inputfile)
                                                                              preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                              postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                              documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                              creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                              keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                              executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                              codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                              devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                              repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                              nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                              binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                              repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                              source
                                                                              
+z = x + y

                                                                              We note that lines starting with # are removed and only the code lines have been kept.

                                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                                              Literate.script — Function
                                                                              Literate.script(inputfile, outputdir; config::Dict=Dict(), kwargs...)

                                                                              Generate a plain script file from inputfile and write the result to outputdir.

                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                                              source

                                                                              4.4. Configuration

                                                                              The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                                              Literate 2.2

                                                                              Passing configuration as a dictionary requires at least Literate version 2.2.

                                                                              Configuration precedence

                                                                              Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                                              Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                                              Literate.DEFAULT_CONFIGURATION — Constant
                                                                              DEFAULT_CONFIGURATION

                                                                              Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                                              Configuration keyDescriptionDefault valueComment
                                                                              nameName of the output file (excluding file extension).filename(inputfile)
                                                                              preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                              postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                              documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                              creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                              keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                              executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                              codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                              devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                              repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                              nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                              binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                              repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                              source
                                                                              \ No newline at end of file diff --git a/v2.4.0/pipeline/index.html b/v2.4.0/pipeline/index.html index 7c0c212..4a011d5 100644 --- a/v2.4.0/pipeline/index.html +++ b/v2.4.0/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                                              Edit on GitHub

                                                                              3. Processing pipeline

                                                                              The generation of output follows the same pipeline for all output formats:

                                                                              1. Pre-processing
                                                                              2. Parsing
                                                                              3. Document generation
                                                                              4. Post-processing
                                                                              5. Writing to file

                                                                              3.1. Pre-processing

                                                                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                                              3.2. Parsing

                                                                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                                              # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                                              Edit on GitHub
                                                                              3. Processing pipeline
                                                                              The generation of output follows the same pipeline for all output formats:
                                                                              1. Pre-processing
                                                                              2. Parsing
                                                                              3. Document generation
                                                                              4. Post-processing
                                                                              5. Writing to file
                                                                              3.1. Pre-processing
                                                                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                                              3.2. Parsing
                                                                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                                              Chunk #2:
                                                                              # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                                              Chunk #3:
                                                                              When adding `x` and `y` together we obtain a new rational number:
                                                                              Chunk #4:
                                                                              z = x + y
                                                                              It is then up to the Document generation step to decide how these chunks should be treated.
                                                                              Custom control over chunk splits
                                                                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                              x = 1 // 3
+y = 2 // 5
                                                                              Chunk #3:
                                                                              When adding `x` and `y` together we obtain a new rational number:
                                                                              Chunk #4:
                                                                              z = x + y
                                                                              It is then up to the Document generation step to decide how these chunks should be treated.
                                                                              Custom control over chunk splits
                                                                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                              x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                                              The example above would result in two consecutive code-chunks.
                                                                              Tip
                                                                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                                              It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                                              3.3. Document generation
                                                                              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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                              • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                                              3.4. Post-processing
                                                                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                                              3.5. Writing to file
                                                                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                                              
+z = x + y

                                                                              The example above would result in two consecutive code-chunks.

                                                                              Tip

                                                                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                                              It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                                              3.3. Document generation

                                                                              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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                              • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                                              3.4. Post-processing

                                                                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                                              3.5. Writing to file

                                                                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                                              \ No newline at end of file diff --git a/v2.4.0/search/index.html b/v2.4.0/search/index.html index 7af2b5d..6b858d8 100644 --- a/v2.4.0/search/index.html +++ b/v2.4.0/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                                              Loading search...

                                                                                +Search · Literate.jl

                                                                                Loading search...

                                                                                  \ No newline at end of file diff --git a/v2.4.0/tips/index.html b/v2.4.0/tips/index.html index c2d8610..ee8e45e 100644 --- a/v2.4.0/tips/index.html +++ b/v2.4.0/tips/index.html @@ -1,5 +1,46 @@ - -7. Tips and Tricks · Literate.jl
                                                                                  Edit on GitHub

                                                                                  7. Tips and Tricks

                                                                                  This section lists some tips and tricks that might be useful for using Literate.

                                                                                  Filesize of generated notebooks

                                                                                  When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.

                                                                                  A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.

                                                                                  In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" and image to be captures as image/png only, you can use

                                                                                  import DisplayAs
+7. Tips and Tricks · Literate.jl
                                                                                  Edit on GitHub
                                                                                  7. Tips and Tricks
                                                                                  This section lists some tips and tricks that might be useful for using Literate.
                                                                                  Filesize of generated notebooks
                                                                                  When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.
                                                                                  A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.
                                                                                  In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" and image to be captures as image/png only, you can use
                                                                                  import DisplayAs
 img = plot(...)
 img = DisplayAs.PNG(img)
                                                                                  This can save some memory, since the image is never captured in e.g. SVG or HTML formats.
                                                                                  Note
                                                                                  It is best to always let the object be showable as text/plain. This can be achieved by nested calls to DisplayAs output types. For example, to limit an image img to be showable as just image/png and text/plain you can use
                                                                                  img = plot(...)
-img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                  
+img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                  \ No newline at end of file diff --git a/v2.5.0/customprocessing/index.html b/v2.5.0/customprocessing/index.html index 00e4959..098b89a 100644 --- a/v2.5.0/customprocessing/index.html +++ b/v2.5.0/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                                                  Edit on GitHub

                                                                                  5. Custom pre- and post-processing

                                                                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                                                  Example: Adding current date

                                                                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                                                  # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                                                  Edit on GitHub
                                                                                  5. Custom pre- and post-processing
                                                                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                                                  Example: Adding current date
                                                                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                                                  # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                                                  where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                                                  function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                  Example: Replacing include calls with included code
                                                                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                  # # Replace includes
+end
                                                                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                  Example: Replacing include calls with included code
                                                                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                  # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                  function replace_includes(str)
+include("file2.jl")
                                                                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                  function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                                                  (of course replace included with your respective files)
                                                                                  Finally, you simply pass this function to e.g. Literate.markdown as
                                                                                  Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                                                  This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                                                  
+end

                                                                                  (of course replace included with your respective files)

                                                                                  Finally, you simply pass this function to e.g. Literate.markdown as

                                                                                  Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                                                  This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                                                  \ No newline at end of file diff --git a/v2.5.0/documenter/index.html b/v2.5.0/documenter/index.html index cdbcc42..d406dc0 100644 --- a/v2.5.0/documenter/index.html +++ b/v2.5.0/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                                                  Edit on GitHub

                                                                                  6. Interaction with Documenter.jl

                                                                                  Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:

                                                                                  Literate.markdown:

                                                                                  • The default code fence will change from
                                                                                    ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                                    Edit on GitHub
                                                                                    6. Interaction with Documenter.jl
                                                                                    Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set documenter = true:
                                                                                    Literate.markdown:
                                                                                    • The default code fence will change from
                                                                                      ```julia
 # code
 ```
                                                                                      to Documenters @example blocks:
                                                                                      ```@examples $(name)
 # code
-```
                                                                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                      ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                                    Literate.notebook:
                                                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                    • Documenter style markdown math
                                                                                      ```math
+```
                                                                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                      ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                                    Literate.notebook:
                                                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                    • Documenter style markdown math
                                                                                      ```math
 \int f dx
 ```
                                                                                      is replaced with notebook compatible
                                                                                      $$
 \int f dx
-$$
                                                                                    Literate.script:
                                                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                    
+$$

                                                                                  Literate.script:

                                                                                  • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                  \ No newline at end of file diff --git a/v2.5.0/fileformat/index.html b/v2.5.0/fileformat/index.html index 59ddb02..990dae1 100644 --- a/v2.5.0/fileformat/index.html +++ b/v2.5.0/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                                                  Edit on GitHub

                                                                                  2. File Format

                                                                                  The source file format for Literate 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.

                                                                                  2.1. Syntax

                                                                                  The basic syntax is simple:

                                                                                  • lines starting with # are treated as markdown,
                                                                                  • all other lines are treated as julia code.

                                                                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                                                  Lets look at a simple example:

                                                                                  # # Rational numbers
+2. File Format · Literate.jl
                                                                                  Edit on GitHub
                                                                                  2. File Format
                                                                                  The source file format for Literate 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.
                                                                                  2.1. Syntax
                                                                                  The basic syntax is simple:
                                                                                  • lines starting with # are treated as markdown,
                                                                                  • all other lines are treated as julia code.
                                                                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                                                  Lets look at a simple example:
                                                                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                  2.2. Filtering Lines
                                                                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                  • #md: line exclusive to markdown output,
                                                                                  • #nb: line exclusive to notebook output,
                                                                                  • #jl: line exclusive to script output,
                                                                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                  Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                                  Literate 2.3
                                                                                  Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                  Tip
                                                                                  The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                  #md # ```@docs
+z = x + y
                                                                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                  2.2. Filtering Lines
                                                                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                  • #md: line exclusive to markdown output,
                                                                                  • #nb: line exclusive to notebook output,
                                                                                  • #jl: line exclusive to script output,
                                                                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                  Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                                  Literate 2.3
                                                                                  Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                  Tip
                                                                                  The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                  #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                                                  The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                                                  using Test                      #src
-@test result == expected_result #src
                                                                                  2.3. Default Replacements
                                                                                  The following convenience "macros"/source placeholders are always expanded:
                                                                                  • @__NAME__:
                                                                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                                                  • @__REPO_ROOT_URL__:
                                                                                    Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                  • @__NBVIEWER_ROOT_URL__:
                                                                                    Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                  • @__BINDER_ROOT_URL__:
                                                                                    Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                                    This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                  Literate 2.1
                                                                                  GitHub Actions support for the macros above requires at least Literate version 2.1.
                                                                                  Literate 2.2
                                                                                  GitLab CI support for the macros above requires at least Literate version 2.2.
                                                                                  
+@test result == expected_result #src

                                                                                  2.3. Default Replacements

                                                                                  The following convenience "macros"/source placeholders are always expanded:

                                                                                  • @__NAME__:

                                                                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                                                  • @__REPO_ROOT_URL__:

                                                                                    Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                  • @__NBVIEWER_ROOT_URL__:

                                                                                    Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                  • @__BINDER_ROOT_URL__:

                                                                                    Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                                    This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                  Literate 2.1

                                                                                  GitHub Actions support for the macros above requires at least Literate version 2.1.

                                                                                  Literate 2.2

                                                                                  GitLab CI support for the macros above requires at least Literate version 2.2.

                                                                                  \ No newline at end of file diff --git a/v2.5.0/generated/example/index.html b/v2.5.0/generated/example/index.html index 85815ba..d32f5d6 100644 --- a/v2.5.0/generated/example/index.html +++ b/v2.5.0/generated/example/index.html @@ -1,7 +1,48 @@ - -8. Example · Literate.jl
                                                                                  Edit on GitHub

                                                                                  8. Example

                                                                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                                                  Basic syntax

                                                                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                                                  x = 1//3
-y = 2//5
                                                                                  2//5

                                                                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                                                  • This line starts with #md and is thus only visible in the markdown output.

                                                                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                                                  x + y
                                                                                  11//15
                                                                                  x * y
                                                                                  2//15

                                                                                  Output Capturing

                                                                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                                                  Note

                                                                                  Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                                                  function foo()
-    println("This string is printed to stdout.")
+8. Example · Literate.jl
                                                                                  Edit on GitHub
                                                                                  8. Example
                                                                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                                                  Basic syntax
                                                                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                                                  x = 1//3
+y = 2//5
                                                                                  2//5
                                                                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                                                  • This line starts with #md and is thus only visible in the markdown output.
                                                                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                                                  x + y
                                                                                  11//15
                                                                                  x * y
                                                                                  2//15
                                                                                  Output Capturing
                                                                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                                                  Note
                                                                                  Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                                                  function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,94 +50,55 @@ foo()
                                                                                  4-element Array{Int64,1}:
  1
  2
  3
- 4
                                                                                  Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                  1 + 1;
                                                                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                  using Plots
+ 4
                                                                                  Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                  1 + 1;
                                                                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                  using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                                                  
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
                                                                                  Custom processing
                                                                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                  x = 123
                                                                                  123
                                                                                  In this case the preprocessing function is defined by
                                                                                  function pre(s::String)
-    s = replace(s, "x = 123" => "y = 321")
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">
                                                                                  Custom processing
                                                                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                  x = 123
                                                                                  123
                                                                                  In this case the preprocessing function is defined by
                                                                                  function pre(s::String)
+    s = replace(s, "x = 123" => "y = 321")
     return s
-end
                                                                                  pre (generic function with 1 method)
                                                                                  Documenter.jl interaction
                                                                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                                  This page was generated using Literate.jl.
                                                                                  
+end
                                                                                  pre (generic function with 1 method)

                                                                                  Documenter.jl interaction

                                                                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                                                                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                                                                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                                                                                  This page was generated using Literate.jl.

                                                                                  \ No newline at end of file diff --git a/v2.5.0/generated/name/index.html b/v2.5.0/generated/name/index.html index 7c630e2..d096de8 100644 --- a/v2.5.0/generated/name/index.html +++ b/v2.5.0/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                                                  Edit on GitHub

                                                                                  Rational numbers

                                                                                  In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                  x = 1//3
                                                                                  1//3
                                                                                  y = 2//5
                                                                                  2//5

                                                                                  When adding x and y together we obtain a new rational number:

                                                                                  z = x + y
                                                                                  11//15
                                                                                  +Rational numbers · Literate.jl
                                                                                  Edit on GitHub

                                                                                  Rational numbers

                                                                                  In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                  x = 1//3
                                                                                  1//3
                                                                                  y = 2//5
                                                                                  2//5

                                                                                  When adding x and y together we obtain a new rational number:

                                                                                  z = x + y
                                                                                  11//15
                                                                                  \ No newline at end of file diff --git a/v2.5.0/index.html b/v2.5.0/index.html index 8b640c7..e881fb1 100644 --- a/v2.5.0/index.html +++ b/v2.5.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                                                  Edit on GitHub

                                                                                  1. Introduction

                                                                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                  What?

                                                                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                  The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                  • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                  • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                  • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                  Why?

                                                                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                  +1. Introduction · Literate.jl
                                                                                  Edit on GitHub

                                                                                  1. Introduction

                                                                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                  What?

                                                                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                  The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                  • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                  • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                  • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                  Why?

                                                                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                  \ No newline at end of file diff --git a/v2.5.0/outputformats/index.html b/v2.5.0/outputformats/index.html index a8593e9..c43cf46 100644 --- a/v2.5.0/outputformats/index.html +++ b/v2.5.0/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                                                  Edit on GitHub

                                                                                  4. Output Formats

                                                                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                                                  # # Rational numbers
+4. Output Formats · Literate.jl
                                                                                  Edit on GitHub
                                                                                  4. Output Formats
                                                                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                                                  and see how this is rendered in each of the output formats.
                                                                                  4.1. Markdown Output
                                                                                  Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                                                  ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,23 +72,23 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                  It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                  ```julia
+```
                                                                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                  It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                  ```julia
 x = 1//3
 ```
 ```
 1//3
-```
                                                                                  In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                  Note
                                                                                  Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                  Literate 2.4
                                                                                  Code execution of markdown output requires at least Literate version 2.4.
                                                                                  See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                  Literate.markdown — Function
                                                                                  Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                  Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                  Literate 2.5
                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                  source
                                                                                  4.2. Notebook Output
                                                                                  Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                  Literate.notebook — Function
                                                                                  Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                  Generate a notebook from inputfile and write the result to outputdir.
                                                                                  Literate 2.5
                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                  source
                                                                                  Notebook metadata
                                                                                  Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                  %% optional ignored text [type] {optional metadata JSON}
                                                                                  Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                  The following would create a 3 slide deck with RISE:
                                                                                  #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
+```
                                                                                  In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                  Note
                                                                                  Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                  Literate 2.4
                                                                                  Code execution of markdown output requires at least Literate version 2.4.
                                                                                  See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                  Literate.markdown — Function
                                                                                  Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                  Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                  Literate 2.5
                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                  source
                                                                                  4.2. Notebook Output
                                                                                  Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                  Literate.notebook — Function
                                                                                  Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                  Generate a notebook from inputfile and write the result to outputdir.
                                                                                  Literate 2.5
                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                  source
                                                                                  Notebook metadata
                                                                                  Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                  %% optional ignored text [type] {optional metadata JSON}
                                                                                  Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                  The following would create a 3 slide deck with RISE:
                                                                                  #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
 # # Some title
 #
-# We're using `#nb` so the metadata is only included in notebook output
+# We're using `#nb` so the metadata is only included in notebook output
 
-#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
+#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
 x = 1//3
 y = 2//5
 
-#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
+#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
 # For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)
                                                                                  4.3. Script Output
                                                                                  Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                                  x = 1//3
 
 y = 2//5
 
-z = x + y
                                                                                  We note that lines starting with # are removed and only the code lines have been kept.
                                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                                                  Literate.script — Function
                                                                                  Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                  Generate a plain script file from inputfile and write the result to outputdir.
                                                                                  Literate 2.5
                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                  source
                                                                                  4.4. Configuration
                                                                                  The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                                                  Literate 2.2
                                                                                  Passing configuration as a dictionary requires at least Literate version 2.2.
                                                                                  Configuration precedence
                                                                                  Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                                                  Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                                                  Literate.DEFAULT_CONFIGURATION — Constant
                                                                                  DEFAULT_CONFIGURATION
                                                                                  Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                                                  Configuration keyDescriptionDefault valueComment
                                                                                  nameName of the output file (excluding file extension).filename(inputfile)
                                                                                  preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                  postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                  documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                  creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                  keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                  executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                  codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                  devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                  repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                  nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                  binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                  repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                  source
                                                                                  
+z = x + y

                                                                                  We note that lines starting with # are removed and only the code lines have been kept.

                                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                                                  Literate.script — Function
                                                                                  Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

                                                                                  Generate a plain script file from inputfile and write the result to outputdir.

                                                                                  Literate 2.5

                                                                                  Default output directory pwd requires at least Literate version 2.5.

                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                                                  source

                                                                                  4.4. Configuration

                                                                                  The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                                                  Literate 2.2

                                                                                  Passing configuration as a dictionary requires at least Literate version 2.2.

                                                                                  Configuration precedence

                                                                                  Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                                                  Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                                                  Literate.DEFAULT_CONFIGURATION — Constant
                                                                                  DEFAULT_CONFIGURATION

                                                                                  Default configuration for Literate.markdown, Literate.notebook and [Literate.script] which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                                                  Configuration keyDescriptionDefault valueComment
                                                                                  nameName of the output file (excluding file extension).filename(inputfile)
                                                                                  preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                  postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                  documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                  creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                  keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                  executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                  codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                  devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                  repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                  nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                  binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                  repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                  source
                                                                                  \ No newline at end of file diff --git a/v2.5.0/pipeline/index.html b/v2.5.0/pipeline/index.html index 2e44e82..03c6493 100644 --- a/v2.5.0/pipeline/index.html +++ b/v2.5.0/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                                                  Edit on GitHub

                                                                                  3. Processing pipeline

                                                                                  The generation of output follows the same pipeline for all output formats:

                                                                                  1. Pre-processing
                                                                                  2. Parsing
                                                                                  3. Document generation
                                                                                  4. Post-processing
                                                                                  5. Writing to file

                                                                                  3.1. Pre-processing

                                                                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                                                  3.2. Parsing

                                                                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                                                  # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                                                  Edit on GitHub
                                                                                  3. Processing pipeline
                                                                                  The generation of output follows the same pipeline for all output formats:
                                                                                  1. Pre-processing
                                                                                  2. Parsing
                                                                                  3. Document generation
                                                                                  4. Post-processing
                                                                                  5. Writing to file
                                                                                  3.1. Pre-processing
                                                                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                                                  3.2. Parsing
                                                                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                                                  Chunk #2:
                                                                                  # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                                                  Chunk #3:
                                                                                  When adding `x` and `y` together we obtain a new rational number:
                                                                                  Chunk #4:
                                                                                  z = x + y
                                                                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                  Custom control over chunk splits
                                                                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                  x = 1 // 3
+y = 2 // 5
                                                                                  Chunk #3:
                                                                                  When adding `x` and `y` together we obtain a new rational number:
                                                                                  Chunk #4:
                                                                                  z = x + y
                                                                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                  Custom control over chunk splits
                                                                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                  x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                                                  The example above would result in two consecutive code-chunks.
                                                                                  Tip
                                                                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                                                  It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                                                  3.3. Document generation
                                                                                  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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                                                  3.4. Post-processing
                                                                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                                                  3.5. Writing to file
                                                                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                                                  
+z = x + y

                                                                                  The example above would result in two consecutive code-chunks.

                                                                                  Tip

                                                                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                                                  It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                                                  3.3. Document generation

                                                                                  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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                                                  3.4. Post-processing

                                                                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                                                  3.5. Writing to file

                                                                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                                                  \ No newline at end of file diff --git a/v2.5.0/search/index.html b/v2.5.0/search/index.html index c96920e..ef26354 100644 --- a/v2.5.0/search/index.html +++ b/v2.5.0/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                                                  Loading search...

                                                                                    +Search · Literate.jl

                                                                                    Loading search...

                                                                                      \ No newline at end of file diff --git a/v2.5.0/tips/index.html b/v2.5.0/tips/index.html index f2aad1b..65f603c 100644 --- a/v2.5.0/tips/index.html +++ b/v2.5.0/tips/index.html @@ -1,5 +1,46 @@ - -7. Tips and Tricks · Literate.jl
                                                                                      Edit on GitHub

                                                                                      7. Tips and Tricks

                                                                                      This section lists some tips and tricks that might be useful for using Literate.

                                                                                      Filesize of generated notebooks

                                                                                      When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.

                                                                                      A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.

                                                                                      In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" and image to be captures as image/png only, you can use

                                                                                      import DisplayAs
+7. Tips and Tricks · Literate.jl
                                                                                      Edit on GitHub
                                                                                      7. Tips and Tricks
                                                                                      This section lists some tips and tricks that might be useful for using Literate.
                                                                                      Filesize of generated notebooks
                                                                                      When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.
                                                                                      A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.
                                                                                      In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" and image to be captures as image/png only, you can use
                                                                                      import DisplayAs
 img = plot(...)
 img = DisplayAs.PNG(img)
                                                                                      This can save some memory, since the image is never captured in e.g. SVG or HTML formats.
                                                                                      Note
                                                                                      It is best to always let the object be showable as text/plain. This can be achieved by nested calls to DisplayAs output types. For example, to limit an image img to be showable as just image/png and text/plain you can use
                                                                                      img = plot(...)
-img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                      
+img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                      \ No newline at end of file diff --git a/v2.5.1/customprocessing/index.html b/v2.5.1/customprocessing/index.html index 1ca2f22..42b9b33 100644 --- a/v2.5.1/customprocessing/index.html +++ b/v2.5.1/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                                                      Edit on GitHub

                                                                                      5. Custom pre- and post-processing

                                                                                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                                                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                                                      Example: Adding current date

                                                                                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                                                      # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                                                      Edit on GitHub
                                                                                      5. Custom pre- and post-processing
                                                                                      Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                                                      preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                                                      Example: Adding current date
                                                                                      As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                                                      # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                                                      where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                                                      function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                                                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                      Example: Replacing include calls with included code
                                                                                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                      # # Replace includes
+end
                                                                                      which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                      Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                      Example: Replacing include calls with included code
                                                                                      Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                      We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                      A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                      # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                                                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                      function replace_includes(str)
+include("file2.jl")
                                                                                      Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                      function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                                                      (of course replace included with your respective files)
                                                                                      Finally, you simply pass this function to e.g. Literate.markdown as
                                                                                      Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                                                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                                                      This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                                                      
+end

                                                                                      (of course replace included with your respective files)

                                                                                      Finally, you simply pass this function to e.g. Literate.markdown as

                                                                                      Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                                                      and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                                                      This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                                                      \ No newline at end of file diff --git a/v2.5.1/documenter/index.html b/v2.5.1/documenter/index.html index 25485ed..d87ee51 100644 --- a/v2.5.1/documenter/index.html +++ b/v2.5.1/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                                                      Edit on GitHub

                                                                                      6. Interaction with Documenter.jl

                                                                                      Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So let's take a look at what will happen if we set documenter = true:

                                                                                      Literate.markdown:

                                                                                      • The default code fence will change from
                                                                                        ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                                        Edit on GitHub
                                                                                        6. Interaction with Documenter.jl
                                                                                        Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So let's take a look at what will happen if we set documenter = true:
                                                                                        Literate.markdown:
                                                                                        • The default code fence will change from
                                                                                          ```julia
 # code
 ```
                                                                                          to Documenters @example blocks:
                                                                                          ```@examples $(name)
 # code
-```
                                                                                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                          ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                                        Literate.notebook:
                                                                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                        • Documenter style markdown math
                                                                                          ```math
+```
                                                                                        • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                          ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                                        Literate.notebook:
                                                                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                        • Documenter style markdown math
                                                                                          ```math
 \int f dx
 ```
                                                                                          is replaced with notebook compatible
                                                                                          $$
 \int f dx
-$$
                                                                                        Literate.script:
                                                                                        • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                        
+$$

                                                                                      Literate.script:

                                                                                      • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                      \ No newline at end of file diff --git a/v2.5.1/fileformat/index.html b/v2.5.1/fileformat/index.html index bba0818..dd84954 100644 --- a/v2.5.1/fileformat/index.html +++ b/v2.5.1/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                                                      Edit on GitHub

                                                                                      2. File Format

                                                                                      The source file format for Literate 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.

                                                                                      2.1. Syntax

                                                                                      The basic syntax is simple:

                                                                                      • lines starting with # are treated as markdown,
                                                                                      • all other lines are treated as julia code.

                                                                                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                                                      Lets look at a simple example:

                                                                                      # # Rational numbers
+2. File Format · Literate.jl
                                                                                      Edit on GitHub
                                                                                      2. File Format
                                                                                      The source file format for Literate 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.
                                                                                      2.1. Syntax
                                                                                      The basic syntax is simple:
                                                                                      • lines starting with # are treated as markdown,
                                                                                      • all other lines are treated as julia code.
                                                                                      Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                                                      Lets look at a simple example:
                                                                                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                                                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                      For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                      2.2. Filtering Lines
                                                                                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                      • #md: line exclusive to markdown output,
                                                                                      • #nb: line exclusive to notebook output,
                                                                                      • #jl: line exclusive to script output,
                                                                                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                      Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                                      Literate 2.3
                                                                                      Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                      Tip
                                                                                      The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                      #md # ```@docs
+z = x + y
                                                                                      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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                      • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                      For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                      There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                      2.2. Filtering Lines
                                                                                      It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                      • #md: line exclusive to markdown output,
                                                                                      • #nb: line exclusive to notebook output,
                                                                                      • #jl: line exclusive to script output,
                                                                                      • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                      Lines starting or ending with one of these tokens are filtered out in the preprocessing step.
                                                                                      Literate 2.3
                                                                                      Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                      Tip
                                                                                      The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                      Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                      #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                                                      The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                                                      using Test                      #src
-@test result == expected_result #src
                                                                                      2.3. Default Replacements
                                                                                      The following convenience "macros"/source placeholders are always expanded:
                                                                                      • @__NAME__:
                                                                                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                                                      • @__REPO_ROOT_URL__:
                                                                                        Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                      • @__NBVIEWER_ROOT_URL__:
                                                                                        Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                      • @__BINDER_ROOT_URL__:
                                                                                        Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                                        [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                                        This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                      Literate 2.1
                                                                                      GitHub Actions support for the macros above requires at least Literate version 2.1.
                                                                                      Literate 2.2
                                                                                      GitLab CI support for the macros above requires at least Literate version 2.2.
                                                                                      
+@test result == expected_result #src

                                                                                      2.3. Default Replacements

                                                                                      The following convenience "macros"/source placeholders are always expanded:

                                                                                      • @__NAME__:

                                                                                        expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                                                      • @__REPO_ROOT_URL__:

                                                                                        Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                      • @__NBVIEWER_ROOT_URL__:

                                                                                        Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                      • @__BINDER_ROOT_URL__:

                                                                                        Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                                        [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                                        This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                      Literate 2.1

                                                                                      GitHub Actions support for the macros above requires at least Literate version 2.1.

                                                                                      Literate 2.2

                                                                                      GitLab CI support for the macros above requires at least Literate version 2.2.

                                                                                      \ No newline at end of file diff --git a/v2.5.1/generated/example/index.html b/v2.5.1/generated/example/index.html index 1be4a1e..811d908 100644 --- a/v2.5.1/generated/example/index.html +++ b/v2.5.1/generated/example/index.html @@ -1,7 +1,48 @@ - -8. Example · Literate.jl
                                                                                      Edit on GitHub

                                                                                      8. Example

                                                                                      This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                                                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                                                      Basic syntax

                                                                                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                                                      x = 1//3
-y = 2//5
                                                                                      2//5

                                                                                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                                                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                                                      • This line starts with #md and is thus only visible in the markdown output.

                                                                                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                                                      x + y
                                                                                      11//15
                                                                                      x * y
                                                                                      2//15

                                                                                      Output Capturing

                                                                                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                                                      Note

                                                                                      Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                                                      function foo()
-    println("This string is printed to stdout.")
+8. Example · Literate.jl
                                                                                      Edit on GitHub
                                                                                      8. Example
                                                                                      This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                                                      It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                                                      Basic syntax
                                                                                      The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                                                      x = 1//3
+y = 2//5
                                                                                      2//5
                                                                                      In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                                                      It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                                                      • This line starts with #md and is thus only visible in the markdown output.
                                                                                      The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                                                      x + y
                                                                                      11//15
                                                                                      x * y
                                                                                      2//15
                                                                                      Output Capturing
                                                                                      Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                                                      Note
                                                                                      Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                                                      function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,94 +50,55 @@ foo()
                                                                                      4-element Array{Int64,1
  1
  2
  3
- 4
                                                                                      Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                      1 + 1;
                                                                                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                      using Plots
+ 4
                                                                                      Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                      1 + 1;
                                                                                      Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                      using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                                                      
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
                                                                                      Custom processing
                                                                                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                      x = 123
                                                                                      123
                                                                                      In this case the preprocessing function is defined by
                                                                                      function pre(s::String)
-    s = replace(s, "x = 123" => "y = 321")
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">
                                                                                      Custom processing
                                                                                      It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                      x = 123
                                                                                      123
                                                                                      In this case the preprocessing function is defined by
                                                                                      function pre(s::String)
+    s = replace(s, "x = 123" => "y = 321")
     return s
-end
                                                                                      pre (generic function with 1 method)
                                                                                      Documenter.jl interaction
                                                                                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                                      This page was generated using Literate.jl.
                                                                                      
+end
                                                                                      pre (generic function with 1 method)

                                                                                      Documenter.jl interaction

                                                                                      In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                                                                                      \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                                                                                      using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                                                                                      This page was generated using Literate.jl.

                                                                                      \ No newline at end of file diff --git a/v2.5.1/generated/name/index.html b/v2.5.1/generated/name/index.html index fbda5d8..bb7ed1c 100644 --- a/v2.5.1/generated/name/index.html +++ b/v2.5.1/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                                                      Edit on GitHub

                                                                                      Rational numbers

                                                                                      In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                      x = 1//3
                                                                                      1//3
                                                                                      y = 2//5
                                                                                      2//5

                                                                                      When adding x and y together we obtain a new rational number:

                                                                                      z = x + y
                                                                                      11//15
                                                                                      +Rational numbers · Literate.jl
                                                                                      Edit on GitHub

                                                                                      Rational numbers

                                                                                      In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                      x = 1//3
                                                                                      1//3
                                                                                      y = 2//5
                                                                                      2//5

                                                                                      When adding x and y together we obtain a new rational number:

                                                                                      z = x + y
                                                                                      11//15
                                                                                      \ No newline at end of file diff --git a/v2.5.1/index.html b/v2.5.1/index.html index 480df42..11b5cd8 100644 --- a/v2.5.1/index.html +++ b/v2.5.1/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                                                      Edit on GitHub

                                                                                      1. Introduction

                                                                                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                      What?

                                                                                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                      The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                      • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                      • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                      • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                      Why?

                                                                                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                      It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                      +1. Introduction · Literate.jl
                                                                                      Edit on GitHub

                                                                                      1. Introduction

                                                                                      Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                      What?

                                                                                      Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                      The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                      The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                      • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                      • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                      • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                      Why?

                                                                                      Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                      It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                      Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                      \ No newline at end of file diff --git a/v2.5.1/outputformats/index.html b/v2.5.1/outputformats/index.html index cf9a896..59a1bf1 100644 --- a/v2.5.1/outputformats/index.html +++ b/v2.5.1/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                                                      Edit on GitHub

                                                                                      4. Output Formats

                                                                                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                                                      # # Rational numbers
+4. Output Formats · Literate.jl
                                                                                      Edit on GitHub
                                                                                      4. Output Formats
                                                                                      When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                                                      # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                                                      and see how this is rendered in each of the output formats.
                                                                                      4.1. Markdown Output
                                                                                      Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                                                      ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,23 +72,23 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                                                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                      It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                      ```julia
+```
                                                                                      We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                      It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                      ```julia
 x = 1//3
 ```
 ```
 1//3
-```
                                                                                      In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                      Note
                                                                                      Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                      Literate 2.4
                                                                                      Code execution of markdown output requires at least Literate version 2.4.
                                                                                      See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                      Literate.markdown — Function
                                                                                      Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                      Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                      Literate 2.5
                                                                                      Default output directory pwd requires at least Literate version 2.5.
                                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                      source
                                                                                      4.2. Notebook Output
                                                                                      Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                      Literate.notebook — Function
                                                                                      Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                      Generate a notebook from inputfile and write the result to outputdir.
                                                                                      Literate 2.5
                                                                                      Default output directory pwd requires at least Literate version 2.5.
                                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                      source
                                                                                      Notebook metadata
                                                                                      Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                      %% optional ignored text [type] {optional metadata JSON}
                                                                                      Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                      The following would create a 3 slide deck with RISE:
                                                                                      #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
+```
                                                                                      In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                      Note
                                                                                      Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                      Literate 2.4
                                                                                      Code execution of markdown output requires at least Literate version 2.4.
                                                                                      See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                      Literate.markdown — Function
                                                                                      Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                      Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                      Literate 2.5
                                                                                      Default output directory pwd requires at least Literate version 2.5.
                                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                      source
                                                                                      4.2. Notebook Output
                                                                                      Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                      We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                      Literate.notebook — Function
                                                                                      Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                      Generate a notebook from inputfile and write the result to outputdir.
                                                                                      Literate 2.5
                                                                                      Default output directory pwd requires at least Literate version 2.5.
                                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                      source
                                                                                      Notebook metadata
                                                                                      Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                      %% optional ignored text [type] {optional metadata JSON}
                                                                                      Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                      The following would create a 3 slide deck with RISE:
                                                                                      #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
 # # Some title
 #
-# We're using `#nb` so the metadata is only included in notebook output
+# We're using `#nb` so the metadata is only included in notebook output
 
-#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
+#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
 x = 1//3
 y = 2//5
 
-#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
+#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
 # For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)
                                                                                      4.3. Script Output
                                                                                      Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                                      x = 1//3
 
 y = 2//5
 
-z = x + y
                                                                                      We note that lines starting with # are removed and only the code lines have been kept.
                                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                                                      Literate.script — Function
                                                                                      Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                      Generate a plain script file from inputfile and write the result to outputdir.
                                                                                      Literate 2.5
                                                                                      Default output directory pwd requires at least Literate version 2.5.
                                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                      source
                                                                                      4.4. Configuration
                                                                                      The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                                                      Literate 2.2
                                                                                      Passing configuration as a dictionary requires at least Literate version 2.2.
                                                                                      Configuration precedence
                                                                                      Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                                                      Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                                                      Literate.DEFAULT_CONFIGURATION — Constant
                                                                                      DEFAULT_CONFIGURATION
                                                                                      Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                                                      Configuration keyDescriptionDefault valueComment
                                                                                      nameName of the output file (excluding file extension).filename(inputfile)
                                                                                      preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                      postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                      documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                      creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                      keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                      executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                      codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                      devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                      repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                      nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                      binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                      repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                      source
                                                                                      
+z = x + y

                                                                                      We note that lines starting with # are removed and only the code lines have been kept.

                                                                                      See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                                                      Literate.script — Function
                                                                                      Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

                                                                                      Generate a plain script file from inputfile and write the result to outputdir.

                                                                                      Literate 2.5

                                                                                      Default output directory pwd requires at least Literate version 2.5.

                                                                                      See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                                                      source

                                                                                      4.4. Configuration

                                                                                      The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                                                      Literate 2.2

                                                                                      Passing configuration as a dictionary requires at least Literate version 2.2.

                                                                                      Configuration precedence

                                                                                      Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                                                      Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                                                      Literate.DEFAULT_CONFIGURATION — Constant
                                                                                      DEFAULT_CONFIGURATION

                                                                                      Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                                                      Configuration keyDescriptionDefault valueComment
                                                                                      nameName of the output file (excluding file extension).filename(inputfile)
                                                                                      preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                      postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                      documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                      creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                      keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                      executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                      codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                      devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                      repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                      nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                      binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                      repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                      source
                                                                                      \ No newline at end of file diff --git a/v2.5.1/pipeline/index.html b/v2.5.1/pipeline/index.html index 09ebbf3..76ab0b8 100644 --- a/v2.5.1/pipeline/index.html +++ b/v2.5.1/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                                                      Edit on GitHub

                                                                                      3. Processing pipeline

                                                                                      The generation of output follows the same pipeline for all output formats:

                                                                                      1. Pre-processing
                                                                                      2. Parsing
                                                                                      3. Document generation
                                                                                      4. Post-processing
                                                                                      5. Writing to file

                                                                                      3.1. Pre-processing

                                                                                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                                                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                                                      3.2. Parsing

                                                                                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                                                      # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                                                      Edit on GitHub
                                                                                      3. Processing pipeline
                                                                                      The generation of output follows the same pipeline for all output formats:
                                                                                      1. Pre-processing
                                                                                      2. Parsing
                                                                                      3. Document generation
                                                                                      4. Post-processing
                                                                                      5. Writing to file
                                                                                      3.1. Pre-processing
                                                                                      The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                                                      The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                                                      3.2. Parsing
                                                                                      After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                                                      Chunk #2:
                                                                                      # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                                                      Chunk #3:
                                                                                      When adding `x` and `y` together we obtain a new rational number:
                                                                                      Chunk #4:
                                                                                      z = x + y
                                                                                      It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                      Custom control over chunk splits
                                                                                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                      x = 1 // 3
+y = 2 // 5
                                                                                      Chunk #3:
                                                                                      When adding `x` and `y` together we obtain a new rational number:
                                                                                      Chunk #4:
                                                                                      z = x + y
                                                                                      It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                      Custom control over chunk splits
                                                                                      Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                      x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                                                      The example above would result in two consecutive code-chunks.
                                                                                      Tip
                                                                                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                                                      It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                                                      3.3. Document generation
                                                                                      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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                                                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                      • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                                                      3.4. Post-processing
                                                                                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                                                      3.5. Writing to file
                                                                                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                                                      
+z = x + y

                                                                                      The example above would result in two consecutive code-chunks.

                                                                                      Tip

                                                                                      The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                                                      It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                                                      3.3. Document generation

                                                                                      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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                                                      • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                      • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                      • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                                                      3.4. Post-processing

                                                                                      When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                                                      3.5. Writing to file

                                                                                      The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                                                      \ No newline at end of file diff --git a/v2.5.1/search/index.html b/v2.5.1/search/index.html index ab7a70a..889d2b7 100644 --- a/v2.5.1/search/index.html +++ b/v2.5.1/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                                                      Loading search...

                                                                                        +Search · Literate.jl

                                                                                        Loading search...

                                                                                          \ No newline at end of file diff --git a/v2.5.1/tips/index.html b/v2.5.1/tips/index.html index d8e9430..de38ec0 100644 --- a/v2.5.1/tips/index.html +++ b/v2.5.1/tips/index.html @@ -1,5 +1,46 @@ - -7. Tips and Tricks · Literate.jl
                                                                                          Edit on GitHub

                                                                                          7. Tips and Tricks

                                                                                          This section lists some tips and tricks that might be useful for using Literate.

                                                                                          Filesize of generated notebooks

                                                                                          When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.

                                                                                          A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.

                                                                                          In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" an image to be captures as image/png only, you can use

                                                                                          import DisplayAs
+7. Tips and Tricks · Literate.jl
                                                                                          Edit on GitHub
                                                                                          7. Tips and Tricks
                                                                                          This section lists some tips and tricks that might be useful for using Literate.
                                                                                          Filesize of generated notebooks
                                                                                          When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.
                                                                                          A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.
                                                                                          In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" an image to be captures as image/png only, you can use
                                                                                          import DisplayAs
 img = plot(...)
 img = DisplayAs.PNG(img)
                                                                                          This can save some memory, since the image is never captured in e.g. SVG or HTML formats.
                                                                                          Note
                                                                                          It is best to always let the object be showable as text/plain. This can be achieved by nested calls to DisplayAs output types. For example, to limit an image img to be showable as just image/png and text/plain you can use
                                                                                          img = plot(...)
-img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                          
+img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                          \ No newline at end of file diff --git a/v2.6.0/customprocessing/index.html b/v2.6.0/customprocessing/index.html index 4f46631..d73d4fe 100644 --- a/v2.6.0/customprocessing/index.html +++ b/v2.6.0/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                                                          Edit on GitHub

                                                                                          5. Custom pre- and post-processing

                                                                                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                                                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                                                          Example: Adding current date

                                                                                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                                                          # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                                                          Edit on GitHub
                                                                                          5. Custom pre- and post-processing
                                                                                          Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                                                          preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                                                          Example: Adding current date
                                                                                          As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                                                          # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                                                          where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                                                          function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                                                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                          Example: Replacing include calls with included code
                                                                                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                          # # Replace includes
+end
                                                                                          which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                          Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                          Example: Replacing include calls with included code
                                                                                          Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                          We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                          A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                          # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                                                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                          function replace_includes(str)
+include("file2.jl")
                                                                                          Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                          function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                                                          (of course replace included with your respective files)
                                                                                          Finally, you simply pass this function to e.g. Literate.markdown as
                                                                                          Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                                                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                                                          This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                                                          
+end

                                                                                          (of course replace included with your respective files)

                                                                                          Finally, you simply pass this function to e.g. Literate.markdown as

                                                                                          Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                                                          and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                                                          This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                                                          \ No newline at end of file diff --git a/v2.6.0/documenter/index.html b/v2.6.0/documenter/index.html index f21b0c0..393469b 100644 --- a/v2.6.0/documenter/index.html +++ b/v2.6.0/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                                                          Edit on GitHub

                                                                                          6. Interaction with Documenter.jl

                                                                                          Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So let's take a look at what will happen if we set documenter = true:

                                                                                          Literate.markdown:

                                                                                          • The default code fence will change from
                                                                                            ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                                            Edit on GitHub
                                                                                            6. Interaction with Documenter.jl
                                                                                            Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So let's take a look at what will happen if we set documenter = true:
                                                                                            Literate.markdown:
                                                                                            • The default code fence will change from
                                                                                              ```julia
 # code
 ```
                                                                                              to Documenters @example blocks:
                                                                                              ```@examples $(name)
 # code
-```
                                                                                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                              ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                                            Literate.notebook:
                                                                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                            • Documenter style markdown math
                                                                                              ```math
+```
                                                                                            • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                              ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                                            Literate.notebook:
                                                                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                            • Documenter style markdown math
                                                                                              ```math
 \int f dx
 ```
                                                                                              is replaced with notebook compatible
                                                                                              $$
 \int f dx
-$$
                                                                                            Literate.script:
                                                                                            • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                            
+$$

                                                                                          Literate.script:

                                                                                          • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                          \ No newline at end of file diff --git a/v2.6.0/fileformat/index.html b/v2.6.0/fileformat/index.html index b09be25..d1a0a8e 100644 --- a/v2.6.0/fileformat/index.html +++ b/v2.6.0/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                                                          Edit on GitHub

                                                                                          2. File Format

                                                                                          The source file format for Literate 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.

                                                                                          2.1. Syntax

                                                                                          The basic syntax is simple:

                                                                                          • lines starting with # are treated as markdown,
                                                                                          • all other lines are treated as julia code.

                                                                                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                                                          Lets look at a simple example:

                                                                                          # # Rational numbers
+2. File Format · Literate.jl
                                                                                          Edit on GitHub
                                                                                          2. File Format
                                                                                          The source file format for Literate 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.
                                                                                          2.1. Syntax
                                                                                          The basic syntax is simple:
                                                                                          • lines starting with # are treated as markdown,
                                                                                          • all other lines are treated as julia code.
                                                                                          Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                                                          Lets look at a simple example:
                                                                                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,9 +51,9 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                                                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                          For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                          2.2. Filtering Lines
                                                                                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                          • #md: line exclusive to markdown output,
                                                                                          • #nb: line exclusive to notebook output,
                                                                                          • #jl: line exclusive to script output,
                                                                                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                          Lines starting or ending with one of these tokens are filtered out in the preprocessing step. In addition, for markdown output, lines ending with #hide are filtered out similar to Documenter.jl.
                                                                                          Difference between `#src` and `#hide`
                                                                                          #src and #hide are quite similar. The only difference is that #src lines are filtered out before execution (if execute=true) and #hide lines are filtered out after execution.
                                                                                          Literate 2.6
                                                                                          The #hide token requires at least Literate version 2.6.
                                                                                          Literate 2.3
                                                                                          Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                          Tip
                                                                                          The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                          #md # ```@docs
+z = x + y
                                                                                          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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                          • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                          For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                          There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                          2.2. Filtering Lines
                                                                                          It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                          • #md: line exclusive to markdown output,
                                                                                          • #nb: line exclusive to notebook output,
                                                                                          • #jl: line exclusive to script output,
                                                                                          • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                          Lines starting or ending with one of these tokens are filtered out in the preprocessing step. In addition, for markdown output, lines ending with #hide are filtered out similar to Documenter.jl.
                                                                                          Difference between `#src` and `#hide`
                                                                                          #src and #hide are quite similar. The only difference is that #src lines are filtered out before execution (if execute=true) and #hide lines are filtered out after execution.
                                                                                          Literate 2.6
                                                                                          The #hide token requires at least Literate version 2.6.
                                                                                          Literate 2.3
                                                                                          Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                          Tip
                                                                                          The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                          Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                          #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                                                          The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                                                          using Test                      #src
-@test result == expected_result #src
                                                                                          2.3. Default Replacements
                                                                                          The following convenience "macros"/source placeholders are always expanded:
                                                                                          • @__NAME__:
                                                                                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                                                          • @__REPO_ROOT_URL__:
                                                                                            Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                          • @__NBVIEWER_ROOT_URL__:
                                                                                            Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                          • @__BINDER_ROOT_URL__:
                                                                                            Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                                            [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                                            This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                          Literate 2.1
                                                                                          GitHub Actions support for the macros above requires at least Literate version 2.1.
                                                                                          Literate 2.2
                                                                                          GitLab CI support for the macros above requires at least Literate version 2.2.
                                                                                          
+@test result == expected_result #src

                                                                                          2.3. Default Replacements

                                                                                          The following convenience "macros"/source placeholders are always expanded:

                                                                                          • @__NAME__:

                                                                                            expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                                                          • @__REPO_ROOT_URL__:

                                                                                            Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                          • @__NBVIEWER_ROOT_URL__:

                                                                                            Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                          • @__BINDER_ROOT_URL__:

                                                                                            Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                                            [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                                            This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                          Literate 2.1

                                                                                          GitHub Actions support for the macros above requires at least Literate version 2.1.

                                                                                          Literate 2.2

                                                                                          GitLab CI support for the macros above requires at least Literate version 2.2.

                                                                                          \ No newline at end of file diff --git a/v2.6.0/generated/example/index.html b/v2.6.0/generated/example/index.html index eb33c62..7a69ef1 100644 --- a/v2.6.0/generated/example/index.html +++ b/v2.6.0/generated/example/index.html @@ -1,7 +1,48 @@ - -8. Example · Literate.jl
                                                                                          Edit on GitHub

                                                                                          8. Example

                                                                                          This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                                                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                                                          Basic syntax

                                                                                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                                                          x = 1//3
-y = 2//5
                                                                                          2//5

                                                                                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                                                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                                                          • This line starts with #md and is thus only visible in the markdown output.

                                                                                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                                                          x + y
                                                                                          11//15
                                                                                          x * y
                                                                                          2//15

                                                                                          Output Capturing

                                                                                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                                                          Note

                                                                                          Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                                                          function foo()
-    println("This string is printed to stdout.")
+8. Example · Literate.jl
                                                                                          Edit on GitHub
                                                                                          8. Example
                                                                                          This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                                                          It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                                                          Basic syntax
                                                                                          The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                                                          x = 1//3
+y = 2//5
                                                                                          2//5
                                                                                          In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                                                          It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                                                          • This line starts with #md and is thus only visible in the markdown output.
                                                                                          The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                                                          x + y
                                                                                          11//15
                                                                                          x * y
                                                                                          2//15
                                                                                          Output Capturing
                                                                                          Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                                                          Note
                                                                                          Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                                                          function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,94 +50,55 @@ foo()
                                                                                          4-element Array{Int64,1
  1
  2
  3
- 4
                                                                                          Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                          1 + 1;
                                                                                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                          using Plots
+ 4
                                                                                          Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                          1 + 1;
                                                                                          Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                          using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                                                          
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
                                                                                          Custom processing
                                                                                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                          x = 123
                                                                                          123
                                                                                          In this case the preprocessing function is defined by
                                                                                          function pre(s::String)
-    s = replace(s, "x = 123" => "y = 321")
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">
                                                                                          Custom processing
                                                                                          It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                          x = 123
                                                                                          123
                                                                                          In this case the preprocessing function is defined by
                                                                                          function pre(s::String)
+    s = replace(s, "x = 123" => "y = 321")
     return s
-end
                                                                                          pre (generic function with 1 method)
                                                                                          Documenter.jl interaction
                                                                                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                                          This page was generated using Literate.jl.
                                                                                          
+end
                                                                                          pre (generic function with 1 method)

                                                                                          Documenter.jl interaction

                                                                                          In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                                                                                          \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                                                                                          using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                                                                                          This page was generated using Literate.jl.

                                                                                          \ No newline at end of file diff --git a/v2.6.0/generated/name/index.html b/v2.6.0/generated/name/index.html index 7bbdd43..3e3c441 100644 --- a/v2.6.0/generated/name/index.html +++ b/v2.6.0/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                                                          Edit on GitHub

                                                                                          Rational numbers

                                                                                          In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                          x = 1//3
                                                                                          1//3
                                                                                          y = 2//5
                                                                                          2//5

                                                                                          When adding x and y together we obtain a new rational number:

                                                                                          z = x + y
                                                                                          11//15
                                                                                          +Rational numbers · Literate.jl
                                                                                          Edit on GitHub

                                                                                          Rational numbers

                                                                                          In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                          x = 1//3
                                                                                          1//3
                                                                                          y = 2//5
                                                                                          2//5

                                                                                          When adding x and y together we obtain a new rational number:

                                                                                          z = x + y
                                                                                          11//15
                                                                                          \ No newline at end of file diff --git a/v2.6.0/index.html b/v2.6.0/index.html index 84467a7..6107a9b 100644 --- a/v2.6.0/index.html +++ b/v2.6.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                                                          Edit on GitHub

                                                                                          1. Introduction

                                                                                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                          What?

                                                                                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                          The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                          • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                          • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                          • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                          Why?

                                                                                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                          It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                          +1. Introduction · Literate.jl
                                                                                          Edit on GitHub

                                                                                          1. Introduction

                                                                                          Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                          What?

                                                                                          Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                          The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                          The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                          • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                          • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                          • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                          Why?

                                                                                          Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                          It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                          Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                          \ No newline at end of file diff --git a/v2.6.0/outputformats/index.html b/v2.6.0/outputformats/index.html index a9775d4..9c0a8c7 100644 --- a/v2.6.0/outputformats/index.html +++ b/v2.6.0/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                                                          Edit on GitHub

                                                                                          4. Output Formats

                                                                                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                                                          # # Rational numbers
+4. Output Formats · Literate.jl
                                                                                          Edit on GitHub
                                                                                          4. Output Formats
                                                                                          When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                                                          # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                                                          and see how this is rendered in each of the output formats.
                                                                                          4.1. Markdown Output
                                                                                          Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                                                          ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,23 +72,23 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                                                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                          It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                          ```julia
+```
                                                                                          We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                          It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                          ```julia
 x = 1//3
 ```
 ```
 1//3
-```
                                                                                          In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                          Note
                                                                                          Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                          Literate 2.4
                                                                                          Code execution of markdown output requires at least Literate version 2.4.
                                                                                          See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                          Literate.markdown — Function
                                                                                          Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                          Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                          Literate 2.5
                                                                                          Default output directory pwd requires at least Literate version 2.5.
                                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                          source
                                                                                          4.2. Notebook Output
                                                                                          Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                          Literate.notebook — Function
                                                                                          Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                          Generate a notebook from inputfile and write the result to outputdir.
                                                                                          Literate 2.5
                                                                                          Default output directory pwd requires at least Literate version 2.5.
                                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                          source
                                                                                          Notebook metadata
                                                                                          Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                          %% optional ignored text [type] {optional metadata JSON}
                                                                                          Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                          The following would create a 3 slide deck with RISE:
                                                                                          #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
+```
                                                                                          In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                          Note
                                                                                          Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                          Literate 2.4
                                                                                          Code execution of markdown output requires at least Literate version 2.4.
                                                                                          See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                          Literate.markdown — Function
                                                                                          Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                          Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                          Literate 2.5
                                                                                          Default output directory pwd requires at least Literate version 2.5.
                                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                          source
                                                                                          4.2. Notebook Output
                                                                                          Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                          We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                          Literate.notebook — Function
                                                                                          Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                          Generate a notebook from inputfile and write the result to outputdir.
                                                                                          Literate 2.5
                                                                                          Default output directory pwd requires at least Literate version 2.5.
                                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                          source
                                                                                          Notebook metadata
                                                                                          Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                          %% optional ignored text [type] {optional metadata JSON}
                                                                                          Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                          The following would create a 3 slide deck with RISE:
                                                                                          #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
 # # Some title
 #
-# We're using `#nb` so the metadata is only included in notebook output
+# We're using `#nb` so the metadata is only included in notebook output
 
-#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
+#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
 x = 1//3
 y = 2//5
 
-#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
+#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
 # For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)
                                                                                          4.3. Script Output
                                                                                          Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                                          x = 1//3
 
 y = 2//5
 
-z = x + y
                                                                                          We note that lines starting with # are removed and only the code lines have been kept.
                                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                                                          Literate.script — Function
                                                                                          Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                          Generate a plain script file from inputfile and write the result to outputdir.
                                                                                          Literate 2.5
                                                                                          Default output directory pwd requires at least Literate version 2.5.
                                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                          source
                                                                                          4.4. Configuration
                                                                                          The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                                                          Literate 2.2
                                                                                          Passing configuration as a dictionary requires at least Literate version 2.2.
                                                                                          Configuration precedence
                                                                                          Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                                                          Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                                                          Literate.DEFAULT_CONFIGURATION — Constant
                                                                                          DEFAULT_CONFIGURATION
                                                                                          Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                                                          Configuration keyDescriptionDefault valueComment
                                                                                          nameName of the output file (excluding file extension).filename(inputfile)
                                                                                          preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                          postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                          documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                          creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                          keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                          executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                          codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                          devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                          repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                          nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                          binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                          repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                          source
                                                                                          
+z = x + y

                                                                                          We note that lines starting with # are removed and only the code lines have been kept.

                                                                                          See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                                                          Literate.script — Function
                                                                                          Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

                                                                                          Generate a plain script file from inputfile and write the result to outputdir.

                                                                                          Literate 2.5

                                                                                          Default output directory pwd requires at least Literate version 2.5.

                                                                                          See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                                                          source

                                                                                          4.4. Configuration

                                                                                          The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                                                          Literate 2.2

                                                                                          Passing configuration as a dictionary requires at least Literate version 2.2.

                                                                                          Configuration precedence

                                                                                          Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                                                          Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                                                          Literate.DEFAULT_CONFIGURATION — Constant
                                                                                          DEFAULT_CONFIGURATION

                                                                                          Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                                                          Configuration keyDescriptionDefault valueComment
                                                                                          nameName of the output file (excluding file extension).filename(inputfile)
                                                                                          preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                          postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                          documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                          creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                          keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                          executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                          codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                          devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                          repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                          nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                          binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                          repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                          source
                                                                                          \ No newline at end of file diff --git a/v2.6.0/pipeline/index.html b/v2.6.0/pipeline/index.html index 8922016..1985b08 100644 --- a/v2.6.0/pipeline/index.html +++ b/v2.6.0/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                                                          Edit on GitHub

                                                                                          3. Processing pipeline

                                                                                          The generation of output follows the same pipeline for all output formats:

                                                                                          1. Pre-processing
                                                                                          2. Parsing
                                                                                          3. Document generation
                                                                                          4. Post-processing
                                                                                          5. Writing to file

                                                                                          3.1. Pre-processing

                                                                                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                                                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                                                          3.2. Parsing

                                                                                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                                                          # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                                                          Edit on GitHub
                                                                                          3. Processing pipeline
                                                                                          The generation of output follows the same pipeline for all output formats:
                                                                                          1. Pre-processing
                                                                                          2. Parsing
                                                                                          3. Document generation
                                                                                          4. Post-processing
                                                                                          5. Writing to file
                                                                                          3.1. Pre-processing
                                                                                          The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                                                          The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                                                          3.2. Parsing
                                                                                          After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                                                          Chunk #2:
                                                                                          # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                                                          Chunk #3:
                                                                                          When adding `x` and `y` together we obtain a new rational number:
                                                                                          Chunk #4:
                                                                                          z = x + y
                                                                                          It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                          Custom control over chunk splits
                                                                                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                          x = 1 // 3
+y = 2 // 5
                                                                                          Chunk #3:
                                                                                          When adding `x` and `y` together we obtain a new rational number:
                                                                                          Chunk #4:
                                                                                          z = x + y
                                                                                          It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                          Custom control over chunk splits
                                                                                          Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                          x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                                                          The example above would result in two consecutive code-chunks.
                                                                                          Tip
                                                                                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                                                          It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                                                          3.3. Document generation
                                                                                          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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                                                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                          • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                                                          3.4. Post-processing
                                                                                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                                                          3.5. Writing to file
                                                                                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                                                          
+z = x + y

                                                                                          The example above would result in two consecutive code-chunks.

                                                                                          Tip

                                                                                          The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                                                          It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                                                          3.3. Document generation

                                                                                          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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                                                          • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                          • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                          • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                                                          3.4. Post-processing

                                                                                          When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                                                          3.5. Writing to file

                                                                                          The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                                                          \ No newline at end of file diff --git a/v2.6.0/search/index.html b/v2.6.0/search/index.html index 38cee19..3c4637d 100644 --- a/v2.6.0/search/index.html +++ b/v2.6.0/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                                                          Loading search...

                                                                                            +Search · Literate.jl

                                                                                            Loading search...

                                                                                              \ No newline at end of file diff --git a/v2.6.0/tips/index.html b/v2.6.0/tips/index.html index 1082002..cbc4518 100644 --- a/v2.6.0/tips/index.html +++ b/v2.6.0/tips/index.html @@ -1,5 +1,46 @@ - -7. Tips and Tricks · Literate.jl
                                                                                              Edit on GitHub

                                                                                              7. Tips and Tricks

                                                                                              This section lists some tips and tricks that might be useful for using Literate.

                                                                                              Filesize of generated notebooks

                                                                                              When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.

                                                                                              A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.

                                                                                              In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" an image to be captures as image/png only, you can use

                                                                                              import DisplayAs
+7. Tips and Tricks · Literate.jl
                                                                                              Edit on GitHub
                                                                                              7. Tips and Tricks
                                                                                              This section lists some tips and tricks that might be useful for using Literate.
                                                                                              Filesize of generated notebooks
                                                                                              When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.
                                                                                              A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.
                                                                                              In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" an image to be captures as image/png only, you can use
                                                                                              import DisplayAs
 img = plot(...)
 img = DisplayAs.PNG(img)
                                                                                              This can save some memory, since the image is never captured in e.g. SVG or HTML formats.
                                                                                              Note
                                                                                              It is best to always let the object be showable as text/plain. This can be achieved by nested calls to DisplayAs output types. For example, to limit an image img to be showable as just image/png and text/plain you can use
                                                                                              img = plot(...)
-img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                              
+img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                              \ No newline at end of file diff --git a/v2.7.0/customprocessing/index.html b/v2.7.0/customprocessing/index.html index b10af72..cc5cc15 100644 --- a/v2.7.0/customprocessing/index.html +++ b/v2.7.0/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                                                              Edit on GitHub

                                                                                              5. Custom pre- and post-processing

                                                                                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                                                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                                                              Example: Adding current date

                                                                                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                                                              # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                                                              Edit on GitHub
                                                                                              5. Custom pre- and post-processing
                                                                                              Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                                                              preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                                                              Example: Adding current date
                                                                                              As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                                                              # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                                                              where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                                                              function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                                                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                              Example: Replacing include calls with included code
                                                                                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                              # # Replace includes
+end
                                                                                              which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                              Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                              Example: Replacing include calls with included code
                                                                                              Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                              We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                              A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                              # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                                                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                              function replace_includes(str)
+include("file2.jl")
                                                                                              Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                              function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                                                              (of course replace included with your respective files)
                                                                                              Finally, you simply pass this function to e.g. Literate.markdown as
                                                                                              Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                                                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                                                              This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                                                              
+end

                                                                                              (of course replace included with your respective files)

                                                                                              Finally, you simply pass this function to e.g. Literate.markdown as

                                                                                              Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                                                              and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                                                              This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                                                              \ No newline at end of file diff --git a/v2.7.0/documenter/index.html b/v2.7.0/documenter/index.html index 807c07a..6a54295 100644 --- a/v2.7.0/documenter/index.html +++ b/v2.7.0/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                                                              Edit on GitHub

                                                                                              6. Interaction with Documenter.jl

                                                                                              Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So let's take a look at what will happen if we set documenter = true:

                                                                                              Literate.markdown:

                                                                                              • The default code fence will change from
                                                                                                ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                                                Edit on GitHub
                                                                                                6. Interaction with Documenter.jl
                                                                                                Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So let's take a look at what will happen if we set documenter = true:
                                                                                                Literate.markdown:
                                                                                                • The default code fence will change from
                                                                                                  ```julia
 # code
 ```
                                                                                                  to Documenters @example blocks:
                                                                                                  ```@examples $(name)
 # code
-```
                                                                                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                                  ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                                                Literate.notebook:
                                                                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                                • Documenter style markdown math
                                                                                                  ```math
+```
                                                                                                • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                                  ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                                                Literate.notebook:
                                                                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                                • Documenter style markdown math
                                                                                                  ```math
 \int f dx
 ```
                                                                                                  is replaced with notebook compatible
                                                                                                  $$
 \int f dx
-$$
                                                                                                Literate.script:
                                                                                                • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                                
+$$

                                                                                              Literate.script:

                                                                                              • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                              \ No newline at end of file diff --git a/v2.7.0/fileformat/index.html b/v2.7.0/fileformat/index.html index 2f1e359..169b531 100644 --- a/v2.7.0/fileformat/index.html +++ b/v2.7.0/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                                                              Edit on GitHub

                                                                                              2. File Format

                                                                                              The source file format for Literate 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.

                                                                                              2.1. Syntax

                                                                                              The basic syntax is simple:

                                                                                              • lines starting with # are treated as markdown,
                                                                                              • all other lines are treated as julia code.

                                                                                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                                                              Lets look at a simple example:

                                                                                              # # Rational numbers
+2. File Format · Literate.jl
                                                                                              Edit on GitHub
                                                                                              2. File Format
                                                                                              The source file format for Literate 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.
                                                                                              2.1. Syntax
                                                                                              The basic syntax is simple:
                                                                                              • lines starting with # are treated as markdown,
                                                                                              • all other lines are treated as julia code.
                                                                                              Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                                                              Lets look at a simple example:
                                                                                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,7 +51,7 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                                                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                              For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                              Multiline comments in Literate 2.7
                                                                                              Literate version 2.7 adds support for Julia multiline comments for markdown input. All multiline comments in the input are rewritten to regular comments as part of the preprocessing step, before any other processing is performed. For Literate to recognize multiline comments it is required that the start token (#=) and end token (=#) are placed on their own lines. Note also that it is allowed to have more than one = in the tokens, for example
                                                                                              #=
+z = x + y
                                                                                              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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                              • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                              For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                              There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                              Multiline comments in Literate 2.7
                                                                                              Literate version 2.7 adds support for Julia multiline comments for markdown input. All multiline comments in the input are rewritten to regular comments as part of the preprocessing step, before any other processing is performed. For Literate to recognize multiline comments it is required that the start token (#=) and end token (=#) are placed on their own lines. Note also that it is allowed to have more than one = in the tokens, for example
                                                                                              #=
 This multiline comment
 is treated as markdown.
 =#
@@ -20,9 +61,9 @@ This is also markdown.
 =====================#
                                                                                              is rewritten to
                                                                                              # This multiline comment
 # is treated as markdown.
 
-# This is also markdown.
                                                                                              2.2. Filtering Lines
                                                                                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                              • #md: line exclusive to markdown output,
                                                                                              • #nb: line exclusive to notebook output,
                                                                                              • #jl: line exclusive to script output,
                                                                                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                              Lines starting or ending with one of these tokens are filtered out in the preprocessing step. In addition, for markdown output, lines ending with #hide are filtered out similar to Documenter.jl.
                                                                                              Difference between `#src` and `#hide`
                                                                                              #src and #hide are quite similar. The only difference is that #src lines are filtered out before execution (if execute=true) and #hide lines are filtered out after execution.
                                                                                              Literate 2.6
                                                                                              The #hide token requires at least Literate version 2.6.
                                                                                              Literate 2.3
                                                                                              Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                              Tip
                                                                                              The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                              #md # ```@docs
+# This is also markdown.
                                                                                              2.2. Filtering Lines
                                                                                              It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                              • #md: line exclusive to markdown output,
                                                                                              • #nb: line exclusive to notebook output,
                                                                                              • #jl: line exclusive to script output,
                                                                                              • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                              Lines starting or ending with one of these tokens are filtered out in the preprocessing step. In addition, for markdown output, lines ending with #hide are filtered out similar to Documenter.jl.
                                                                                              Difference between `#src` and `#hide`
                                                                                              #src and #hide are quite similar. The only difference is that #src lines are filtered out before execution (if execute=true) and #hide lines are filtered out after execution.
                                                                                              Literate 2.6
                                                                                              The #hide token requires at least Literate version 2.6.
                                                                                              Literate 2.3
                                                                                              Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                              Tip
                                                                                              The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                              Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                              #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                                                              The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                                                              using Test                      #src
-@test result == expected_result #src
                                                                                              2.3. Default Replacements
                                                                                              The following convenience "macros"/source placeholders are always expanded:
                                                                                              • @__NAME__:
                                                                                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                                                              • @__REPO_ROOT_URL__:
                                                                                                Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                              • @__NBVIEWER_ROOT_URL__:
                                                                                                Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                              • @__BINDER_ROOT_URL__:
                                                                                                Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                                                [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                                                This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                              Literate 2.1
                                                                                              GitHub Actions support for the macros above requires at least Literate version 2.1.
                                                                                              Literate 2.2
                                                                                              GitLab CI support for the macros above requires at least Literate version 2.2.
                                                                                              
+@test result == expected_result #src

                                                                                              2.3. Default Replacements

                                                                                              The following convenience "macros"/source placeholders are always expanded:

                                                                                              • @__NAME__:

                                                                                                expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                                                              • @__REPO_ROOT_URL__:

                                                                                                Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                              • @__NBVIEWER_ROOT_URL__:

                                                                                                Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                              • @__BINDER_ROOT_URL__:

                                                                                                Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                                                [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                                                This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                              Literate 2.1

                                                                                              GitHub Actions support for the macros above requires at least Literate version 2.1.

                                                                                              Literate 2.2

                                                                                              GitLab CI support for the macros above requires at least Literate version 2.2.

                                                                                              \ No newline at end of file diff --git a/v2.7.0/generated/example/index.html b/v2.7.0/generated/example/index.html index dee6409..338abfa 100644 --- a/v2.7.0/generated/example/index.html +++ b/v2.7.0/generated/example/index.html @@ -1,7 +1,48 @@ - -8. Example · Literate.jl
                                                                                              Edit on GitHub

                                                                                              8. Example

                                                                                              This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                                                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                                                              Basic syntax

                                                                                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                                                              x = 1//3
-y = 2//5
                                                                                              2//5

                                                                                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                                                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                                                              • This line starts with #md and is thus only visible in the markdown output.

                                                                                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                                                              x + y
                                                                                              11//15
                                                                                              x * y
                                                                                              2//15

                                                                                              Output Capturing

                                                                                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                                                              Note

                                                                                              Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                                                              function foo()
-    println("This string is printed to stdout.")
+8. Example · Literate.jl
                                                                                              Edit on GitHub
                                                                                              8. Example
                                                                                              This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                                                              It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                                                              Basic syntax
                                                                                              The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                                                              x = 1//3
+y = 2//5
                                                                                              2//5
                                                                                              In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                                                              It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                                                              • This line starts with #md and is thus only visible in the markdown output.
                                                                                              The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                                                              x + y
                                                                                              11//15
                                                                                              x * y
                                                                                              2//15
                                                                                              Output Capturing
                                                                                              Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                                                              Note
                                                                                              Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                                                              function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,94 +50,55 @@ foo()
                                                                                              4-element Array{Int64,1
  1
  2
  3
- 4
                                                                                              Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                              1 + 1;
                                                                                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                              using Plots
+ 4
                                                                                              Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                              1 + 1;
                                                                                              Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                              using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                                                              
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
                                                                                              Custom processing
                                                                                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                              x = 123
                                                                                              123
                                                                                              In this case the preprocessing function is defined by
                                                                                              function pre(s::String)
-    s = replace(s, "x = 123" => "y = 321")
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">
                                                                                              Custom processing
                                                                                              It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                              x = 123
                                                                                              123
                                                                                              In this case the preprocessing function is defined by
                                                                                              function pre(s::String)
+    s = replace(s, "x = 123" => "y = 321")
     return s
-end
                                                                                              pre (generic function with 1 method)
                                                                                              Documenter.jl interaction
                                                                                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                                              This page was generated using Literate.jl.
                                                                                              
+end
                                                                                              pre (generic function with 1 method)

                                                                                              Documenter.jl interaction

                                                                                              In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                                                                                              \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                                                                                              using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                                                                                              This page was generated using Literate.jl.

                                                                                              \ No newline at end of file diff --git a/v2.7.0/generated/name/index.html b/v2.7.0/generated/name/index.html index 6d8db59..73b0dec 100644 --- a/v2.7.0/generated/name/index.html +++ b/v2.7.0/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                                                              Edit on GitHub

                                                                                              Rational numbers

                                                                                              In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                              x = 1//3
                                                                                              1//3
                                                                                              y = 2//5
                                                                                              2//5

                                                                                              When adding x and y together we obtain a new rational number:

                                                                                              z = x + y
                                                                                              11//15
                                                                                              +Rational numbers · Literate.jl
                                                                                              Edit on GitHub

                                                                                              Rational numbers

                                                                                              In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                              x = 1//3
                                                                                              1//3
                                                                                              y = 2//5
                                                                                              2//5

                                                                                              When adding x and y together we obtain a new rational number:

                                                                                              z = x + y
                                                                                              11//15
                                                                                              \ No newline at end of file diff --git a/v2.7.0/index.html b/v2.7.0/index.html index 97cf503..47d52dc 100644 --- a/v2.7.0/index.html +++ b/v2.7.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                                                              Edit on GitHub

                                                                                              1. Introduction

                                                                                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                              What?

                                                                                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                              The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                              • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                              • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                              • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                              Why?

                                                                                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                              It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                              +1. Introduction · Literate.jl
                                                                                              Edit on GitHub

                                                                                              1. Introduction

                                                                                              Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                              What?

                                                                                              Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                              The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                              The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                              • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                              • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                              • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                              Why?

                                                                                              Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                              It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                              Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                              \ No newline at end of file diff --git a/v2.7.0/outputformats/index.html b/v2.7.0/outputformats/index.html index 7883afa..c429671 100644 --- a/v2.7.0/outputformats/index.html +++ b/v2.7.0/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                                                              Edit on GitHub

                                                                                              4. Output Formats

                                                                                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                                                              # # Rational numbers
+4. Output Formats · Literate.jl
                                                                                              Edit on GitHub
                                                                                              4. Output Formats
                                                                                              When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                                                              # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                                                              and see how this is rendered in each of the output formats.
                                                                                              4.1. Markdown Output
                                                                                              Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                                                              ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,23 +72,23 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                                                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                              It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                              ```julia
+```
                                                                                              We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                              It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                              ```julia
 x = 1//3
 ```
 ```
 1//3
-```
                                                                                              In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                              Note
                                                                                              Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                              Literate 2.4
                                                                                              Code execution of markdown output requires at least Literate version 2.4.
                                                                                              See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                              Literate.markdown — Function
                                                                                              Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                              Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                              Literate 2.5
                                                                                              Default output directory pwd requires at least Literate version 2.5.
                                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                              source
                                                                                              4.2. Notebook Output
                                                                                              Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                              Literate.notebook — Function
                                                                                              Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                              Generate a notebook from inputfile and write the result to outputdir.
                                                                                              Literate 2.5
                                                                                              Default output directory pwd requires at least Literate version 2.5.
                                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                              source
                                                                                              Notebook metadata
                                                                                              Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                              %% optional ignored text [type] {optional metadata JSON}
                                                                                              Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                              The following would create a 3 slide deck with RISE:
                                                                                              #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
+```
                                                                                              In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                              Note
                                                                                              Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                              Literate 2.4
                                                                                              Code execution of markdown output requires at least Literate version 2.4.
                                                                                              See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                              Literate.markdown — Function
                                                                                              Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                              Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                              Literate 2.5
                                                                                              Default output directory pwd requires at least Literate version 2.5.
                                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                              source
                                                                                              4.2. Notebook Output
                                                                                              Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                              We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                              Literate.notebook — Function
                                                                                              Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                              Generate a notebook from inputfile and write the result to outputdir.
                                                                                              Literate 2.5
                                                                                              Default output directory pwd requires at least Literate version 2.5.
                                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                              source
                                                                                              Notebook metadata
                                                                                              Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                              %% optional ignored text [type] {optional metadata JSON}
                                                                                              Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                              The following would create a 3 slide deck with RISE:
                                                                                              #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
 # # Some title
 #
-# We're using `#nb` so the metadata is only included in notebook output
+# We're using `#nb` so the metadata is only included in notebook output
 
-#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
+#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
 x = 1//3
 y = 2//5
 
-#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
+#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
 # For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)
                                                                                              4.3. Script Output
                                                                                              Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                                              x = 1//3
 
 y = 2//5
 
-z = x + y
                                                                                              We note that lines starting with # are removed and only the code lines have been kept.
                                                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                                                              Literate.script — Function
                                                                                              Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                              Generate a plain script file from inputfile and write the result to outputdir.
                                                                                              Literate 2.5
                                                                                              Default output directory pwd requires at least Literate version 2.5.
                                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                              source
                                                                                              4.4. Configuration
                                                                                              The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                                                              Literate 2.2
                                                                                              Passing configuration as a dictionary requires at least Literate version 2.2.
                                                                                              Configuration precedence
                                                                                              Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                                                              Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                                                              Literate.DEFAULT_CONFIGURATION — Constant
                                                                                              DEFAULT_CONFIGURATION
                                                                                              Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                                                              Configuration keyDescriptionDefault valueComment
                                                                                              nameName of the output file (excluding file extension).filename(inputfile)
                                                                                              preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                              postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                              documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                              creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                              keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                              executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                              codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                              devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                              repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                              nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                              binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                              repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                              source
                                                                                              
+z = x + y

                                                                                              We note that lines starting with # are removed and only the code lines have been kept.

                                                                                              See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                                                              Literate.script — Function
                                                                                              Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

                                                                                              Generate a plain script file from inputfile and write the result to outputdir.

                                                                                              Literate 2.5

                                                                                              Default output directory pwd requires at least Literate version 2.5.

                                                                                              See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                                                              source

                                                                                              4.4. Configuration

                                                                                              The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                                                              Literate 2.2

                                                                                              Passing configuration as a dictionary requires at least Literate version 2.2.

                                                                                              Configuration precedence

                                                                                              Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                                                              Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                                                              Literate.DEFAULT_CONFIGURATION — Constant
                                                                                              DEFAULT_CONFIGURATION

                                                                                              Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                                                              Configuration keyDescriptionDefault valueComment
                                                                                              nameName of the output file (excluding file extension).filename(inputfile)
                                                                                              preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                              postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                              documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                              creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                              keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                              executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                              codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                              devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                              repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                              nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                              binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                              repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                              source
                                                                                              \ No newline at end of file diff --git a/v2.7.0/pipeline/index.html b/v2.7.0/pipeline/index.html index 8cf4ece..6aa19bb 100644 --- a/v2.7.0/pipeline/index.html +++ b/v2.7.0/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                                                              Edit on GitHub

                                                                                              3. Processing pipeline

                                                                                              The generation of output follows the same pipeline for all output formats:

                                                                                              1. Pre-processing
                                                                                              2. Parsing
                                                                                              3. Document generation
                                                                                              4. Post-processing
                                                                                              5. Writing to file

                                                                                              3.1. Pre-processing

                                                                                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                                                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                                                              3.2. Parsing

                                                                                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                                                              # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                                                              Edit on GitHub
                                                                                              3. Processing pipeline
                                                                                              The generation of output follows the same pipeline for all output formats:
                                                                                              1. Pre-processing
                                                                                              2. Parsing
                                                                                              3. Document generation
                                                                                              4. Post-processing
                                                                                              5. Writing to file
                                                                                              3.1. Pre-processing
                                                                                              The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                                                              The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                                                              3.2. Parsing
                                                                                              After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                                                              Chunk #2:
                                                                                              # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                                                              Chunk #3:
                                                                                              When adding `x` and `y` together we obtain a new rational number:
                                                                                              Chunk #4:
                                                                                              z = x + y
                                                                                              It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                              Custom control over chunk splits
                                                                                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                              x = 1 // 3
+y = 2 // 5
                                                                                              Chunk #3:
                                                                                              When adding `x` and `y` together we obtain a new rational number:
                                                                                              Chunk #4:
                                                                                              z = x + y
                                                                                              It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                              Custom control over chunk splits
                                                                                              Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                              x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                                                              The example above would result in two consecutive code-chunks.
                                                                                              Tip
                                                                                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                                                              It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                                                              3.3. Document generation
                                                                                              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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                                                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                              • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                                                              3.4. Post-processing
                                                                                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                                                              3.5. Writing to file
                                                                                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                                                              
+z = x + y

                                                                                              The example above would result in two consecutive code-chunks.

                                                                                              Tip

                                                                                              The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                                                              It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                                                              3.3. Document generation

                                                                                              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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                                                              • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                              • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                              • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                                                              3.4. Post-processing

                                                                                              When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                                                              3.5. Writing to file

                                                                                              The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                                                              \ No newline at end of file diff --git a/v2.7.0/search/index.html b/v2.7.0/search/index.html index 5a9ea2b..45155d3 100644 --- a/v2.7.0/search/index.html +++ b/v2.7.0/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                                                              Loading search...

                                                                                                +Search · Literate.jl

                                                                                                Loading search...

                                                                                                  \ No newline at end of file diff --git a/v2.7.0/tips/index.html b/v2.7.0/tips/index.html index f511a80..eb93f46 100644 --- a/v2.7.0/tips/index.html +++ b/v2.7.0/tips/index.html @@ -1,5 +1,46 @@ - -7. Tips and Tricks · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  7. Tips and Tricks

                                                                                                  This section lists some tips and tricks that might be useful for using Literate.

                                                                                                  Filesize of generated notebooks

                                                                                                  When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.

                                                                                                  A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.

                                                                                                  In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" an image to be captures as image/png only, you can use

                                                                                                  import DisplayAs
+7. Tips and Tricks · Literate.jl
                                                                                                  Edit on GitHub
                                                                                                  7. Tips and Tricks
                                                                                                  This section lists some tips and tricks that might be useful for using Literate.
                                                                                                  Filesize of generated notebooks
                                                                                                  When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.
                                                                                                  A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.
                                                                                                  In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" an image to be captures as image/png only, you can use
                                                                                                  import DisplayAs
 img = plot(...)
 img = DisplayAs.PNG(img)
                                                                                                  This can save some memory, since the image is never captured in e.g. SVG or HTML formats.
                                                                                                  Note
                                                                                                  It is best to always let the object be showable as text/plain. This can be achieved by nested calls to DisplayAs output types. For example, to limit an image img to be showable as just image/png and text/plain you can use
                                                                                                  img = plot(...)
-img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                                  
+img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                                  \ No newline at end of file diff --git a/v2.8.0/customprocessing/index.html b/v2.8.0/customprocessing/index.html index f3469da..e6e5597 100644 --- a/v2.8.0/customprocessing/index.html +++ b/v2.8.0/customprocessing/index.html @@ -1,29 +1,70 @@ - -5. Custom pre- and post-processing · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  5. Custom pre- and post-processing

                                                                                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.

                                                                                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.

                                                                                                  Example: Adding current date

                                                                                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:

                                                                                                  # # Example
+5. Custom pre- and post-processing · Literate.jl
                                                                                                  Edit on GitHub
                                                                                                  5. Custom pre- and post-processing
                                                                                                  Since all packages are different, and may have different demands on how 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 there might be situations where you need to manually hook into the generation and change things. In Literate 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 (Literate.markdown, Literate.notebook and Literate.script) 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.
                                                                                                  preprocess is sent the raw input that is read from the source file (modulo the default line ending transformation). postprocess is given different things depending on the output: For markdown and script output postprocess is given the content String just before writing it to the output file, but for notebook output postprocess is given the dictionary representing the notebook, since, in general, this is more useful.
                                                                                                  Example: Adding current date
                                                                                                  As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a preprocess function that splices the date into the source for us. Consider the following source file:
                                                                                                  # # Example
 # This example was generated DATEOFTODAY
 
 x = 1 // 3
                                                                                                  where DATEOFTODAY is a placeholder, to make it easier for our preprocess function to find the location. Now, lets define the preprocess function, for example
                                                                                                  function update_date(content)
-    content = replace(content, "DATEOFTODAY" => Date(now()))
+    content = replace(content, "DATEOFTODAY" => Date(now()))
     return content
-end
                                                                                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                                  Example: Replacing include calls with included code
                                                                                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                                  # # Replace includes
+end
                                                                                                  which would replace every occurrence of "DATEOFTODAY" with the current date. We would now simply give this function to the generator, for example:
                                                                                                  Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
                                                                                                  Example: Replacing include calls with included code
                                                                                                  Let's say that we have some individual example files file1, file2, ... etc. that are runnable and also following the style of Literate. These files could be for example used in the test suite of your package.
                                                                                                  We want to group them all into a single page in our documentation, but we do not want to copy paste the content of file1, ... for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
                                                                                                  A very easy way to do this is using preprocess to interchange include statements with file content. First, create a runnable .jl following the format of Literate
                                                                                                  # # Replace includes
 # This is an example to replace `include` calls with the actual file content.
 
-include("file1.jl")
+include("file1.jl")
 
 # Cool, we just saw the result of the above code snippet. Here is one more:
 
-include("file2.jl")
                                                                                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                                  function replace_includes(str)
+include("file2.jl")
                                                                                                  Let's say we have saved this file as examples.jl. Then, you want to properly define a pre-processing function:
                                                                                                  function replace_includes(str)
 
-    included = ["file1.jl", "file2.jl"]
+    included = ["file1.jl", "file2.jl"]
 
     # Here the path loads the files from their proper directory,
     # which may not be the directory of the `examples.jl` file!
-    path = "directory/to/example/files/"
+    path = "directory/to/example/files/"
 
     for ex in included
         content = read(path*ex, String)
-        str = replace(str, "include(\"$(ex)\")" => content)
+        str = replace(str, "include(\"$(ex)\")" => content)
     end
     return str
-end
                                                                                                  (of course replace included with your respective files)
                                                                                                  Finally, you simply pass this function to e.g. Literate.markdown as
                                                                                                  Literate.markdown("examples.jl", "path/to/save/markdown";
-                  name = "markdown_file_name", preprocess = replace_includes)
                                                                                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!
                                                                                                  This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The  example files, included together in the  stexamples.jl file, are processed by literate via this make.jl  file to generate the markdown and code cells of the documentation.
                                                                                                  
+end

                                                                                                  (of course replace included with your respective files)

                                                                                                  Finally, you simply pass this function to e.g. Literate.markdown as

                                                                                                  Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)

                                                                                                  and you will see that in the final output file (here markdown_file_name.md) the include statements are replaced with the actual code to be included!

                                                                                                  This approach is used for generating the examples in the documentation of the TimeseriesPrediction.jl package. The example files, included together in the stexamples.jl file, are processed by literate via this make.jl file to generate the markdown and code cells of the documentation.

                                                                                                  \ No newline at end of file diff --git a/v2.8.0/documenter/index.html b/v2.8.0/documenter/index.html index 495cabf..8acc0ec 100644 --- a/v2.8.0/documenter/index.html +++ b/v2.8.0/documenter/index.html @@ -1,12 +1,53 @@ - -6. Interaction with Documenter.jl · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  6. Interaction with Documenter.jl

                                                                                                  Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So let's take a look at what will happen if we set documenter = true:

                                                                                                  Literate.markdown:

                                                                                                  • The default code fence will change from
                                                                                                    ```julia
+6. Interaction with Documenter.jl · Literate.jl
                                                                                                    Edit on GitHub
                                                                                                    6. Interaction with Documenter.jl
                                                                                                    Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So let's take a look at what will happen if we set documenter = true:
                                                                                                    Literate.markdown:
                                                                                                    • The default code fence will change from
                                                                                                      ```julia
 # code
 ```
                                                                                                      to Documenters @example blocks:
                                                                                                      ```@examples $(name)
 # code
-```
                                                                                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                                      ```@meta
-EditURL = "$(relpath(inputfile, outputdir))"
-```
                                                                                                    Literate.notebook:
                                                                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                                    • Documenter style markdown math
                                                                                                      ```math
+```
                                                                                                    • The following @meta block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the source file rather than the generated .md file:
                                                                                                      ```@meta
+EditURL = "$(relpath(inputfile, outputdir))"
+```
                                                                                                    Literate.notebook:
                                                                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the notebook.
                                                                                                    • Documenter style markdown math
                                                                                                      ```math
 \int f dx
 ```
                                                                                                      is replaced with notebook compatible
                                                                                                      $$
 \int f dx
-$$
                                                                                                    Literate.script:
                                                                                                    • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                                    
+$$

                                                                                                  Literate.script:

                                                                                                  • Documenter style @refs and @id will be removed. This means that you can use @ref and @id in the source file without them leaking to the script.
                                                                                                  \ No newline at end of file diff --git a/v2.8.0/fileformat/index.html b/v2.8.0/fileformat/index.html index d54e6ae..544b978 100644 --- a/v2.8.0/fileformat/index.html +++ b/v2.8.0/fileformat/index.html @@ -1,5 +1,46 @@ - -2. File Format · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  2. File Format

                                                                                                  The source file format for Literate 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.

                                                                                                  2.1. Syntax

                                                                                                  The basic syntax is simple:

                                                                                                  • lines starting with # are treated as markdown,
                                                                                                  • all other lines are treated as julia code.

                                                                                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

                                                                                                  Lets look at a simple example:

                                                                                                  # # Rational numbers
+2. File Format · Literate.jl
                                                                                                  Edit on GitHub
                                                                                                  2. File Format
                                                                                                  The source file format for Literate 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.
                                                                                                  2.1. Syntax
                                                                                                  The basic syntax is simple:
                                                                                                  • lines starting with # are treated as markdown,
                                                                                                  • all other lines are treated as julia code.
                                                                                                  Leading whitespace is allowed before #, but it will be removed when generating the output. Since #-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.
                                                                                                  Lets look at a simple example:
                                                                                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -10,7 +51,7 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y
                                                                                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                                  Multiline comments in Literate 2.7
                                                                                                  Literate version 2.7 adds support for Julia multiline comments for markdown input. All multiline comments in the input are rewritten to regular comments as part of the preprocessing step, before any other processing is performed. For Literate to recognize multiline comments it is required that the start token (#=) and end token (=#) are placed on their own lines. Note also that it is allowed to have more than one = in the tokens, for example
                                                                                                  #=
+z = x + y
                                                                                                  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 (for example in the test/runtests.jl script, to include the example in the test suite).
                                                                                                  • The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.
                                                                                                  For simple use this is all you need to know. The following additional special syntax can also be used:
                                                                                                  There is also some default convenience replacements that will always be performed, see Default Replacements.
                                                                                                  Multiline comments in Literate 2.7
                                                                                                  Literate version 2.7 adds support for Julia multiline comments for markdown input. All multiline comments in the input are rewritten to regular comments as part of the preprocessing step, before any other processing is performed. For Literate to recognize multiline comments it is required that the start token (#=) and end token (=#) are placed on their own lines. Note also that it is allowed to have more than one = in the tokens, for example
                                                                                                  #=
 This multiline comment
 is treated as markdown.
 =#
@@ -20,9 +61,9 @@ This is also markdown.
 =====================#
                                                                                                  is rewritten to
                                                                                                  # This multiline comment
 # is treated as markdown.
 
-# This is also markdown.
                                                                                                  2.2. Filtering Lines
                                                                                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                                  • #md: line exclusive to markdown output,
                                                                                                  • #nb: line exclusive to notebook output,
                                                                                                  • #jl: line exclusive to script output,
                                                                                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                                  Lines starting or ending with one of these tokens are filtered out in the preprocessing step. In addition, for markdown output, lines ending with #hide are filtered out similar to Documenter.jl.
                                                                                                  Difference between `#src` and `#hide`
                                                                                                  #src and #hide are quite similar. The only difference is that #src lines are filtered out before execution (if execute=true) and #hide lines are filtered out after execution.
                                                                                                  Literate 2.6
                                                                                                  The #hide token requires at least Literate version 2.6.
                                                                                                  Literate 2.3
                                                                                                  Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                                  Tip
                                                                                                  The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                                  #md # ```@docs
+# This is also markdown.
                                                                                                  2.2. Filtering Lines
                                                                                                  It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:
                                                                                                  • #md: line exclusive to markdown output,
                                                                                                  • #nb: line exclusive to notebook output,
                                                                                                  • #jl: line exclusive to script output,
                                                                                                  • #src: line exclusive to the source code and thus filtered out unconditionally.
                                                                                                  Lines starting or ending with one of these tokens are filtered out in the preprocessing step. In addition, for markdown output, lines ending with #hide are filtered out similar to Documenter.jl.
                                                                                                  Difference between `#src` and `#hide`
                                                                                                  #src and #hide are quite similar. The only difference is that #src lines are filtered out before execution (if execute=true) and #hide lines are filtered out after execution.
                                                                                                  Literate 2.6
                                                                                                  The #hide token requires at least Literate version 2.6.
                                                                                                  Literate 2.3
                                                                                                  Filter tokens at the end of the line requires at least Literate version 2.3.
                                                                                                  Tip
                                                                                                  The tokens can also be negated, for example a line starting with #!nb would be included in markdown and script output, but filtered out for notebook output.
                                                                                                  Suppose, for example, that we want to include a docstring within a @docs block 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:
                                                                                                  #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 the leading #md from the lines. Beware that the space after the tag is also removed.
                                                                                                  The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:
                                                                                                  using Test                      #src
-@test result == expected_result #src
                                                                                                  2.3. Default Replacements
                                                                                                  The following convenience "macros"/source placeholders are always expanded:
                                                                                                  • @__NAME__:
                                                                                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).
                                                                                                  • @__REPO_ROOT_URL__:
                                                                                                    Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                                  • @__NBVIEWER_ROOT_URL__:
                                                                                                    Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                                  • @__BINDER_ROOT_URL__:
                                                                                                    Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:
                                                                                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
                                                                                                    This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.
                                                                                                  Literate 2.1
                                                                                                  GitHub Actions support for the macros above requires at least Literate version 2.1.
                                                                                                  Literate 2.2
                                                                                                  GitLab CI support for the macros above requires at least Literate version 2.2.
                                                                                                  
+@test result == expected_result #src

                                                                                                  2.3. Default Replacements

                                                                                                  The following convenience "macros"/source placeholders are always expanded:

                                                                                                  • @__NAME__:

                                                                                                    expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

                                                                                                  • @__REPO_ROOT_URL__:

                                                                                                    Can be used to link to files in the repository. For example @__REPO_ROOT_URL__/src/Literate.jl would link to the source of the Literate module. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                                  • @__NBVIEWER_ROOT_URL__:

                                                                                                    Can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                                  • @__BINDER_ROOT_URL__:

                                                                                                    Can be used if you want a link that opens the generated notebook in https://mybinder.org/. For example, to add a binder-badge in e.g. the HTML output you can use:

                                                                                                    [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)

                                                                                                    This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see Configuration.

                                                                                                  Literate 2.1

                                                                                                  GitHub Actions support for the macros above requires at least Literate version 2.1.

                                                                                                  Literate 2.2

                                                                                                  GitLab CI support for the macros above requires at least Literate version 2.2.

                                                                                                  \ No newline at end of file diff --git a/v2.8.0/generated/example/index.html b/v2.8.0/generated/example/index.html index 6d84a76..574c27b 100644 --- a/v2.8.0/generated/example/index.html +++ b/v2.8.0/generated/example/index.html @@ -1,7 +1,48 @@ - -8. Example · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  8. Example

                                                                                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

                                                                                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

                                                                                                  Basic syntax

                                                                                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

                                                                                                  x = 1//3
-y = 2//5
                                                                                                  2//5

                                                                                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

                                                                                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

                                                                                                  • This line starts with #md and is thus only visible in the markdown output.

                                                                                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

                                                                                                  x + y
                                                                                                  11//15
                                                                                                  x * y
                                                                                                  2//15

                                                                                                  Output Capturing

                                                                                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

                                                                                                  Note

                                                                                                  Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.

                                                                                                  function foo()
-    println("This string is printed to stdout.")
+8. Example · Literate.jl
                                                                                                  Edit on GitHub
                                                                                                  8. Example
                                                                                                  This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.
                                                                                                  It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.
                                                                                                  Basic syntax
                                                                                                  The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:
                                                                                                  x = 1//3
+y = 2//5
                                                                                                  2//5
                                                                                                  In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.
                                                                                                  It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):
                                                                                                  • This line starts with #md and is thus only visible in the markdown output.
                                                                                                  The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.
                                                                                                  x + y
                                                                                                  11//15
                                                                                                  x * y
                                                                                                  2//15
                                                                                                  Output Capturing
                                                                                                  Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.
                                                                                                  Note
                                                                                                  Note that Documenter currently only displays output to stdout/stderr if there is no other result to show. Since the vector [1, 2, 3, 4] is returned from foo, the printing of "This string is printed to stdout." is hidden.
                                                                                                  function foo()
+    println("This string is printed to stdout.")
     return [1, 2, 3, 4]
 end
 
@@ -9,94 +50,55 @@ foo()
                                                                                                  4-element Array{Int64,1
  1
  2
  3
- 4
                                                                                                  Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                                  1 + 1;
                                                                                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                                  using Plots
+ 4
                                                                                                  Just like in the REPL, outputs ending with a semicolon hides the output:
                                                                                                  1 + 1;
                                                                                                  Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package
                                                                                                  using Plots
 x = range(0, stop=6π, length=1000)
 y1 = sin.(x)
 y2 = cos.(x)
-plot(x, [y1, y2])
                                                                                                  
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-  
-    
-  
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
                                                                                                  Custom processing
                                                                                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                                  x = 123
                                                                                                  123
                                                                                                  In this case the preprocessing function is defined by
                                                                                                  function pre(s::String)
-    s = replace(s, "x = 123" => "y = 321")
+  " style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none">
                                                                                                  Custom processing
                                                                                                  It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.
                                                                                                  x = 123
                                                                                                  123
                                                                                                  In this case the preprocessing function is defined by
                                                                                                  function pre(s::String)
+    s = replace(s, "x = 123" => "y = 321")
     return s
-end
                                                                                                  pre (generic function with 1 method)
                                                                                                  Documenter.jl interaction
                                                                                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:
                                                                                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]
                                                                                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.
                                                                                                  This page was generated using Literate.jl.
                                                                                                  
+end
                                                                                                  pre (generic function with 1 method)

                                                                                                  Documenter.jl interaction

                                                                                                  In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

                                                                                                  \[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

                                                                                                  using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

                                                                                                  This page was generated using Literate.jl.

                                                                                                  \ No newline at end of file diff --git a/v2.8.0/generated/name/index.html b/v2.8.0/generated/name/index.html index 6811c7b..9e11a91 100644 --- a/v2.8.0/generated/name/index.html +++ b/v2.8.0/generated/name/index.html @@ -1,2 +1,43 @@ - -Rational numbers · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  Rational numbers

                                                                                                  In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                                  x = 1//3
                                                                                                  1//3
                                                                                                  y = 2//5
                                                                                                  2//5

                                                                                                  When adding x and y together we obtain a new rational number:

                                                                                                  z = x + y
                                                                                                  11//15
                                                                                                  +Rational numbers · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  Rational numbers

                                                                                                  In julia rational numbers can be constructed with the // operator. Lets define two rational numbers, x and y:

                                                                                                  x = 1//3
                                                                                                  1//3
                                                                                                  y = 2//5
                                                                                                  2//5

                                                                                                  When adding x and y together we obtain a new rational number:

                                                                                                  z = x + y
                                                                                                  11//15
                                                                                                  \ No newline at end of file diff --git a/v2.8.0/index.html b/v2.8.0/index.html index 7d93a16..ce10c7c 100644 --- a/v2.8.0/index.html +++ b/v2.8.0/index.html @@ -1,2 +1,43 @@ - -1. Introduction · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  1. Introduction

                                                                                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                                  What?

                                                                                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                                  The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                                  • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                                  • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                                  • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                                  Why?

                                                                                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl @example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                                  +1. Introduction · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  1. Introduction

                                                                                                  Welcome to the documentation for Literate – a simplistic package for Literate Programming.

                                                                                                  What?

                                                                                                  Literate is a package that generates markdown pages (for e.g. Documenter.jl), and Jupyter notebooks, from the same source file. There is also an option to "clean" the source from all metadata, and produce a pure Julia script.

                                                                                                  The main design goal is simplicity. It should be simple to use, and the syntax should be simple. In short, all you have to do is to write a commented julia script!

                                                                                                  The public interface consists of three functions, all of which take the same script file as input, but generate different output:

                                                                                                  • Literate.markdown generates a markdown file. Code snippets can be executed and the results included in the output.
                                                                                                  • Literate.notebook generates a notebook. Code snippets can be executed and the results included in the output.
                                                                                                  • Literate.script generates a plain script file scrubbed from all metadata and special syntax.

                                                                                                  Why?

                                                                                                  Examples 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 Literate 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. Notebooks are great for showcasing a package, but they are not so great with version control, like git. The reason being that a notebook is a very "rich" format since it contains output and other metadata. Changes to the notebook thus result in large diffs, which makes it harder to review the actual changes.

                                                                                                  It is also common that packages include examples in the documentation, for example by using Documenter.jl@example-blocks. This is also great, but it is not quite as interactive as a notebook, for the users who prefer that.

                                                                                                  Literate tries to solve the problems above by creating the output as a part of the doc build. Literate generates the output based on a single source file which makes it easier to maintain, test, and keep the manual and your example notebooks in sync.

                                                                                                  \ No newline at end of file diff --git a/v2.8.0/outputformats/index.html b/v2.8.0/outputformats/index.html index 878327d..a20b80b 100644 --- a/v2.8.0/outputformats/index.html +++ b/v2.8.0/outputformats/index.html @@ -1,5 +1,46 @@ - -4. Output Formats · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  4. Output Formats

                                                                                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:

                                                                                                  # # Rational numbers
+4. Output Formats · Literate.jl
                                                                                                  Edit on GitHub
                                                                                                  4. Output Formats
                                                                                                  When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
                                                                                                  # # Rational numbers
 #
 # In julia rational numbers can be constructed with the `//` operator.
 # Lets define two rational numbers, `x` and `y`:
@@ -11,7 +52,7 @@ y = 2//5
 # When adding `x` and `y` together we obtain a new rational number:
 
 z = x + y
                                                                                                  and see how this is rendered in each of the output formats.
                                                                                                  4.1. Markdown Output
                                                                                                  Markdown output is generated by Literate.markdown. The (default) markdown output of the source snippet above is as follows:
                                                                                                  ```@meta
-EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
+EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl"
 ```
 
 # Rational numbers
@@ -31,23 +72,23 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```
                                                                                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                                  It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                                  ```julia
+```
                                                                                                  We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.
                                                                                                  It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become
                                                                                                  ```julia
 x = 1//3
 ```
 ```
 1//3
-```
                                                                                                  In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                                  Note
                                                                                                  Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                                  Literate 2.4
                                                                                                  Code execution of markdown output requires at least Literate version 2.4.
                                                                                                  See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                                  Literate.markdown — Function
                                                                                                  Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                                  Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                                  Literate 2.5
                                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                                  source
                                                                                                  4.2. Notebook Output
                                                                                                  Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                                  Literate.notebook — Function
                                                                                                  Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                                  Generate a notebook from inputfile and write the result to outputdir.
                                                                                                  Literate 2.5
                                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                                  source
                                                                                                  Notebook metadata
                                                                                                  Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                                  %% optional ignored text [type] {optional metadata JSON}
                                                                                                  Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                                  The following would create a 3 slide deck with RISE:
                                                                                                  #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
+```
                                                                                                  In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (png or jpeg) Literate will include the image representation of the output.
                                                                                                  Note
                                                                                                  Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.
                                                                                                  Literate 2.4
                                                                                                  Code execution of markdown output requires at least Literate version 2.4.
                                                                                                  See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.
                                                                                                  Literate.markdown — Function
                                                                                                  Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                                  Generate a markdown file from inputfile and write the result to the directory outputdir.
                                                                                                  Literate 2.5
                                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                                  source
                                                                                                  4.2. Notebook Output
                                                                                                  Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.
                                                                                                  We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.
                                                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.
                                                                                                  Literate.notebook — Function
                                                                                                  Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                                  Generate a notebook from inputfile and write the result to outputdir.
                                                                                                  Literate 2.5
                                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                                  source
                                                                                                  Notebook metadata
                                                                                                  Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows
                                                                                                  %% optional ignored text [type] {optional metadata JSON}
                                                                                                  Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.
                                                                                                  The following would create a 3 slide deck with RISE:
                                                                                                  #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
 # # Some title
 #
-# We're using `#nb` so the metadata is only included in notebook output
+# We're using `#nb` so the metadata is only included in notebook output
 
-#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
+#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
 x = 1//3
 y = 2//5
 
-#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
+#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
 # For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)
                                                                                                  4.3. Script Output
                                                                                                  Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:
                                                                                                  x = 1//3
 
 y = 2//5
 
-z = x + y
                                                                                                  We note that lines starting with # are removed and only the code lines have been kept.
                                                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.script.
                                                                                                  Literate.script — Function
                                                                                                  Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
                                                                                                  Generate a plain script file from inputfile and write the result to outputdir.
                                                                                                  Literate 2.5
                                                                                                  Default output directory pwd requires at least Literate version 2.5.
                                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.
                                                                                                  source
                                                                                                  4.4. Configuration
                                                                                                  The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.
                                                                                                  Literate 2.2
                                                                                                  Passing configuration as a dictionary requires at least Literate version 2.2.
                                                                                                  Configuration precedence
                                                                                                  Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.
                                                                                                  Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.
                                                                                                  Literate.DEFAULT_CONFIGURATION — Constant
                                                                                                  DEFAULT_CONFIGURATION
                                                                                                  Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. See the manual section about Configuration for more information.
                                                                                                  Configuration keyDescriptionDefault valueComment
                                                                                                  nameName of the output file (excluding file extension).filename(inputfile)
                                                                                                  preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                                  postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                                  documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                                  creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                                  keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                                  executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                                  codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                                  devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                                  repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                                  nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                                  binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                                  repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                                  source
                                                                                                  
+z = x + y

                                                                                                  We note that lines starting with # are removed and only the code lines have been kept.

                                                                                                  See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

                                                                                                  Literate.script — Function
                                                                                                  Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

                                                                                                  Generate a plain script file from inputfile and write the result to outputdir.

                                                                                                  Literate 2.5

                                                                                                  Default output directory pwd requires at least Literate version 2.5.

                                                                                                  See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

                                                                                                  source

                                                                                                  4.4. Configuration

                                                                                                  The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

                                                                                                  Literate 2.2

                                                                                                  Passing configuration as a dictionary requires at least Literate version 2.2.

                                                                                                  Configuration precedence

                                                                                                  Individual keyword arguments takes precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary takes precedence over the default.

                                                                                                  Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

                                                                                                  Literate.DEFAULT_CONFIGURATION — Constant
                                                                                                  DEFAULT_CONFIGURATION

                                                                                                  Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. See the manual section about Configuration for more information.

                                                                                                  Configuration keyDescriptionDefault valueComment
                                                                                                  nameName of the output file (excluding file extension).filename(inputfile)
                                                                                                  preprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                                  postprocessCustom preprocessing function mapping String to String.identitySee Custom pre- and post-processing.
                                                                                                  documenterBoolean signaling that the source contains Documenter.jl elements.trueSee Interaction with Documenter.
                                                                                                  creditBoolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.true
                                                                                                  keep_commentsWhen true, keeps markdown lines as comments in the output script.falseOnly applicable for Literate.script.
                                                                                                  executeWhether to execute and capture the output.true (notebook), false (markdown)Only applicable for Literate.notebook and Literate.markdown. For markdown this requires at least Literate 2.4.
                                                                                                  codefencePair containing opening and closing fence for wrapping code blocks."```julia" => "```"If documenter is true the default is "```@example"=>"```".
                                                                                                  devurlURL for "in-development" docs."dev"See Documenter docs. Unused if repo_root_url/nbviewer_root_url/binder_root_url are set.
                                                                                                  repo_root_urlURL to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
                                                                                                  nbviewer_root_urlURL to the root of the repository as seen on nbviewer.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
                                                                                                  binder_root_urlURL to the root of the repository as seen on mybinder.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
                                                                                                  repo_root_pathFilepath to the root of the repository.-Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
                                                                                                  source
                                                                                                  \ No newline at end of file diff --git a/v2.8.0/pipeline/index.html b/v2.8.0/pipeline/index.html index dcaafaf..96d5e5e 100644 --- a/v2.8.0/pipeline/index.html +++ b/v2.8.0/pipeline/index.html @@ -1,5 +1,46 @@ - -3. Processing pipeline · Literate.jl
                                                                                                  Edit on GitHub

                                                                                                  3. Processing pipeline

                                                                                                  The generation of output follows the same pipeline for all output formats:

                                                                                                  1. Pre-processing
                                                                                                  2. Parsing
                                                                                                  3. Document generation
                                                                                                  4. Post-processing
                                                                                                  5. Writing to file

                                                                                                  3.1. Pre-processing

                                                                                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.

                                                                                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.

                                                                                                  3.2. Parsing

                                                                                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the Syntax section. Lets consider the example from the previous section with each line categorized:

                                                                                                  # # Rational numbers                                                     <- markdown
+3. Processing pipeline · Literate.jl
                                                                                                  Edit on GitHub
                                                                                                  3. Processing pipeline
                                                                                                  The generation of output follows the same pipeline for all output formats:
                                                                                                  1. Pre-processing
                                                                                                  2. Parsing
                                                                                                  3. Document generation
                                                                                                  4. Post-processing
                                                                                                  5. Writing to file
                                                                                                  3.1. Pre-processing
                                                                                                  The first step is pre-processing of the input file. The file is read to a String. The first processing step is to apply the user specified pre-processing function, see Custom pre- and post-processing.
                                                                                                  The next step is to perform all of the built-in default replacements. CRLF style line endings ("\r\n") are replaced with LF line endings ("\n") to simplify internal processing. Next, line filtering is performed, see Filtering Lines, meaning that lines starting with #md, #nb or #jl are handled (either just the token itself is removed, or the full line, depending on the output target). The last pre-processing step is to expand the convenience "macros" described in Default Replacements is expanded.
                                                                                                  3.2. Parsing
                                                                                                  After the preprocessing the file is parsed. The first step is to categorize each line and mark them as either markdown or code according to the rules described in the 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
@@ -10,7 +51,7 @@ y = 2 // 5                                                               <- c
                                                                          <- 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                                                     ┐
+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`:                         ┘
@@ -26,7 +67,7 @@ z = x + y                                                                ┘ cod
 In julia rational numbers can be constructed with the `//` operator.
 Lets define two rational numbers, `x` and `y`:
                                                                                                  Chunk #2:
                                                                                                  # Define variable x and y
 x = 1 // 3
-y = 2 // 5
                                                                                                  Chunk #3:
                                                                                                  When adding `x` and `y` together we obtain a new rational number:
                                                                                                  Chunk #4:
                                                                                                  z = x + y
                                                                                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                                  Custom control over chunk splits
                                                                                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                                  x = 1 // 3
+y = 2 // 5
                                                                                                  Chunk #3:
                                                                                                  When adding `x` and `y` together we obtain a new rational number:
                                                                                                  Chunk #4:
                                                                                                  z = x + y
                                                                                                  It is then up to the Document generation step to decide how these chunks should be treated.
                                                                                                  Custom control over chunk splits
                                                                                                  Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different @example blocks or notebook cells. The #- token can be used for this purpose. All lines starting with #- are used as "chunk-splitters":
                                                                                                  x = 1 // 3
 y = 2 // 5
 #-
-z = x + y
                                                                                                  The example above would result in two consecutive code-chunks.
                                                                                                  Tip
                                                                                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.
                                                                                                  It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.
                                                                                                  3.3. Document generation
                                                                                                  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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:
                                                                                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.
                                                                                                  3.4. Post-processing
                                                                                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.
                                                                                                  3.5. Writing to file
                                                                                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.
                                                                                                  
+z = x + y

                                                                                                  The example above would result in two consecutive code-chunks.

                                                                                                  Tip

                                                                                                  The rest of the line, after #-, is discarded, so it is possible to use e.g. #------------- as a chunk splitter, which may make the source code more readable.

                                                                                                  It is also possible to use #+ as a chunk splitter. The difference between #+ and #- is that #+ enables Documenter's "continued"-blocks, see the Documenter manual.

                                                                                                  3.3. Document generation

                                                                                                  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 described in more detail in the Output format sections: Markdown Output, Notebook Output and Script Output. Using the default settings, the following is happening:

                                                                                                  • Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to @example-blocks),
                                                                                                  • Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,
                                                                                                  • Script output: markdown chunks are discarded, code chunks are printed as-is.

                                                                                                  3.4. Post-processing

                                                                                                  When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See Custom pre- and post-processing.

                                                                                                  3.5. Writing to file

                                                                                                  The last step of the generation is writing to file. The result is written to $(outputdir)/$(name)(.md|.ipynb|.jl) where outputdir is the output directory supplied by the user (for example docs/generated), and name is a user supplied filename. It is recommended to add the output directory to .gitignore since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.

                                                                                                  \ No newline at end of file diff --git a/v2.8.0/search/index.html b/v2.8.0/search/index.html index 7b2680a..f302a1e 100644 --- a/v2.8.0/search/index.html +++ b/v2.8.0/search/index.html @@ -1,2 +1,43 @@ - -Search · Literate.jl

                                                                                                  Loading search...

                                                                                                    +Search · Literate.jl

                                                                                                    Loading search...

                                                                                                      \ No newline at end of file diff --git a/v2.8.0/tips/index.html b/v2.8.0/tips/index.html index e4a6f9b..77da78c 100644 --- a/v2.8.0/tips/index.html +++ b/v2.8.0/tips/index.html @@ -1,5 +1,46 @@ - -7. Tips and Tricks · Literate.jl
                                                                                                      Edit on GitHub

                                                                                                      7. Tips and Tricks

                                                                                                      This section lists some tips and tricks that might be useful for using Literate.

                                                                                                      Filesize of generated notebooks

                                                                                                      When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.

                                                                                                      A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.

                                                                                                      In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" an image to be captures as image/png only, you can use

                                                                                                      import DisplayAs
+7. Tips and Tricks · Literate.jl
                                                                                                      Edit on GitHub
                                                                                                      7. Tips and Tricks
                                                                                                      This section lists some tips and tricks that might be useful for using Literate.
                                                                                                      Filesize of generated notebooks
                                                                                                      When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or MIMEs, just like IJulia.jl does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.
                                                                                                      A common example is images, which can often be displayed in multiple formats, e.g. PNG (image/png), SVG (image/svg+xml) and HTML (text/html). As a result, the filesize of the generated notebook can become large.
                                                                                                      In order to remedy this you can use the clever Julia package DisplayAs to limit the output capabilities of and object. For example, to "force" an image to be captures as image/png only, you can use
                                                                                                      import DisplayAs
 img = plot(...)
 img = DisplayAs.PNG(img)
                                                                                                      This can save some memory, since the image is never captured in e.g. SVG or HTML formats.
                                                                                                      Note
                                                                                                      It is best to always let the object be showable as text/plain. This can be achieved by nested calls to DisplayAs output types. For example, to limit an image img to be showable as just image/png and text/plain you can use
                                                                                                      img = plot(...)
-img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                                      
+img = DisplayAs.Text(DisplayAs.PNG(img))
                                                                                                      \ No newline at end of file