build based on 42f3941

dev/customprocessing/index.html

@@ -26,4 +26,4 @@ include(&quot;file2.jl&quot;)</code></pre><p>Let&#39;s say we have saved this fi
     end
     return str
 end</code></pre><p>(of course replace <code>included</code> with your respective files)</p><p>Finally, you simply pass this function to e.g. <a href="../outputformats/#Literate.markdown"><code>Literate.markdown</code></a> as</p><pre><code class="language-julia">Literate.markdown(&quot;examples.jl&quot;, &quot;path/to/save/markdown&quot;;
-                  name = &quot;markdown_file_name&quot;, preprocess = replace_includes)</code></pre><p>and you will see that in the final output file (here <code>markdown_file_name.md</code>) the <code>include</code> statements are replaced with the actual code to be included!</p><p>This approach is used for generating <a href="https://juliadynamics.github.io/TimeseriesPrediction.jl/latest/stexamples/">the examples</a> in the documentation of the <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl">TimeseriesPrediction.jl</a> package. The  <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl/tree/dcb080376a7861716147c04e45c473f55bb9a078/examples">example files</a>, included together in the  <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl/blob/dcb080376a7861716147c04e45c473f55bb9a078/docs/src/stexamples.jl">stexamples.jl</a> file, are processed by literate via this <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl/blob/dcb080376a7861716147c04e45c473f55bb9a078/docs/make.jl">make.jl</a>  file to generate the markdown and code cells of the documentation.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../outputformats/">« <strong>4.</strong> Output formats</a><a class="docs-footer-nextpage" href="../documenter/"><strong>6.</strong> Interaction with Documenter.jl »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 01:03">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+                  name = &quot;markdown_file_name&quot;, preprocess = replace_includes)</code></pre><p>and you will see that in the final output file (here <code>markdown_file_name.md</code>) the <code>include</code> statements are replaced with the actual code to be included!</p><p>This approach is used for generating <a href="https://juliadynamics.github.io/TimeseriesPrediction.jl/latest/stexamples/">the examples</a> in the documentation of the <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl">TimeseriesPrediction.jl</a> package. The  <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl/tree/dcb080376a7861716147c04e45c473f55bb9a078/examples">example files</a>, included together in the  <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl/blob/dcb080376a7861716147c04e45c473f55bb9a078/docs/src/stexamples.jl">stexamples.jl</a> file, are processed by literate via this <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl/blob/dcb080376a7861716147c04e45c473f55bb9a078/docs/make.jl">make.jl</a>  file to generate the markdown and code cells of the documentation.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../outputformats/">« <strong>4.</strong> Output formats</a><a class="docs-footer-nextpage" href="../documenter/"><strong>6.</strong> Interaction with Documenter.jl »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 02:39">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/documenter/index.html

@@ -9,4 +9,4 @@ EditURL = "$(relpath(inputfile, outputdir))"
 \int f dx
 ```</code></pre>is replaced with notebook compatible<pre><code class="nohighlight">$$
 \int f dx
-$$</code></pre></li></ul><h3 id="[Literate.script](@ref):"><a class="docs-heading-anchor" href="#[Literate.script](@ref):"><a href="../outputformats/#Literate.script"><code>Literate.script</code></a>:</a><a id="[Literate.script](@ref):-1"></a><a class="docs-heading-anchor-permalink" href="#[Literate.script](@ref):" title="Permalink"></a></h3><ul><li>Documenter style <code>@ref</code>s and <code>@id</code> will be removed. This means that you can use <code>@ref</code> and <code>@id</code> in the source file without them leaking to the script.</li></ul></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../customprocessing/">« <strong>5.</strong> Custom pre- and post-processing</a><a class="docs-footer-nextpage" href="../tips/"><strong>7.</strong> Tips and tricks »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 01:03">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+$$</code></pre></li></ul><h3 id="[Literate.script](@ref):"><a class="docs-heading-anchor" href="#[Literate.script](@ref):"><a href="../outputformats/#Literate.script"><code>Literate.script</code></a>:</a><a id="[Literate.script](@ref):-1"></a><a class="docs-heading-anchor-permalink" href="#[Literate.script](@ref):" title="Permalink"></a></h3><ul><li>Documenter style <code>@ref</code>s and <code>@id</code> will be removed. This means that you can use <code>@ref</code> and <code>@id</code> in the source file without them leaking to the script.</li></ul></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../customprocessing/">« <strong>5.</strong> Custom pre- and post-processing</a><a class="docs-footer-nextpage" href="../tips/"><strong>7.</strong> Tips and tricks »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 02:39">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/fileformat/index.html

@@ -10,7 +10,7 @@ y = 2//5
 
 # When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y</code></pre><p>In the lines starting with <code>#</code> we can use regular markdown syntax, for example the <code>#</code> used for the heading and the backticks for formatting code. The other lines are regular julia code. We note a couple of things:</p><ul><li>The script is valid julia, which means that we can <code>include</code> it and the example will run (for example in the <code>test/runtests.jl</code> script, to include the example in the test suite).</li><li>The script is &quot;self-explanatory&quot;, i.e. the markdown lines works as comments and thus serve as good documentation on its own.</li></ul><p>For simple use this is all you need to know. The following additional special syntax can also be used:</p><ul><li><code>#md</code>, <code>#nb</code>, <code>#jl</code>, <code>#src</code>: tags to filter lines, see <a href="#Filtering-lines">Filtering lines</a>,</li><li><code>#-</code> (<code>#+</code>): tag to manually control chunk-splits, see <a href="../pipeline/#Custom-control-over-chunk-splits">Custom control over chunk splits</a>.</li></ul><p>There is also some default convenience replacements that will always be performed, see <a href="#Default-replacements">Default replacements</a>.</p><h3 id="Multiline-comments"><a class="docs-heading-anchor" href="#Multiline-comments">Multiline comments</a><a id="Multiline-comments-1"></a><a class="docs-heading-anchor-permalink" href="#Multiline-comments" title="Permalink"></a></h3><p>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 (<code>#=</code>) and end token (<code>=#</code>) are placed <em>on their own lines</em>. Note also that it is allowed to have more than one <code>=</code> in the tokens, for example</p><pre><code class="language-juila">#=
+z = x + y</code></pre><p>In the lines starting with <code>#</code> we can use regular markdown syntax, for example the <code>#</code> used for the heading and the backticks for formatting code. The other lines are regular julia code. We note a couple of things:</p><ul><li>The script is valid julia, which means that we can <code>include</code> it and the example will run (for example in the <code>test/runtests.jl</code> script, to include the example in the test suite).</li><li>The script is &quot;self-explanatory&quot;, i.e. the markdown lines works as comments and thus serve as good documentation on its own.</li></ul><p>For simple use this is all you need to know. The following additional special syntax can also be used:</p><ul><li><code>#md</code>, <code>#nb</code>, <code>#jl</code>, <code>#src</code>: tags to filter lines, see <a href="#Filtering-lines">Filtering lines</a>,</li><li><code>#-</code> (<code>#+</code>): tag to manually control chunk-splits, see <a href="../pipeline/#Custom-control-over-chunk-splits">Custom control over chunk splits</a>.</li></ul><p>There is also some default convenience replacements that will always be performed, see <a href="#Default-replacements">Default replacements</a>.</p><h3 id="Multiline-comments-and-markdown-strings"><a class="docs-heading-anchor" href="#Multiline-comments-and-markdown-strings">Multiline comments and markdown strings</a><a id="Multiline-comments-and-markdown-strings-1"></a><a class="docs-heading-anchor-permalink" href="#Multiline-comments-and-markdown-strings" title="Permalink"></a></h3><p>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 (<code>#=</code>) and end token (<code>=#</code>) are placed <em>on their own lines</em>. Note also that it is allowed to have more than one <code>=</code> in the tokens, for example</p><pre><code class="language-juila">#=
 This multiline comment
 is treated as markdown.
 =#
@@ -20,9 +20,13 @@ This is also markdown.
 =====================#</code></pre><p>is rewritten to</p><pre><code class="language-juila"># This multiline comment
 # is treated as markdown.
 
-# This is also markdown.</code></pre><h2 id="Filtering-lines"><a class="docs-heading-anchor" href="#Filtering-lines"><strong>2.2.</strong> Filtering lines</a><a id="Filtering-lines-1"></a><a class="docs-heading-anchor-permalink" href="#Filtering-lines" title="Permalink"></a></h2><p>It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of &quot;tokens&quot; that can be used to mark the purpose of certain lines:</p><ul><li><code>#md</code>: line exclusive to markdown output,</li><li><code>#nb</code>: line exclusive to notebook output,</li><li><code>#jl</code>: line exclusive to script output,</li><li><code>#src</code>: line exclusive to the source code and thus filtered out unconditionally.</li></ul><p>Lines <em>starting</em> or <em>ending</em> with one of these tokens are filtered out in the <a href="../pipeline/#Pre-processing">preprocessing step</a>. In addition, for markdown output, lines ending with <code>#hide</code> are filtered out similar to Documenter.jl.</p><div class="admonition is-info"><header class="admonition-header">Difference between `#src` and `#hide`</header><div class="admonition-body"><p><code>#src</code> and <code>#hide</code> are quite similar. The only difference is that <code>#src</code> lines are filtered out <em>before</em> execution (if <code>execute=true</code>) and <code>#hide</code> lines are filtered out <em>after</em> execution.</p></div></div><div class="admonition is-success"><header class="admonition-header">Tip</header><div class="admonition-body"><p>The tokens can also be negated, for example a line starting with <code>#!nb</code> would be included in markdown and script output, but filtered out for notebook output.</p></div></div><p>Suppose, for example, that we want to include a docstring within a <code>@docs</code> block using Documenter. Obviously we don&#39;t want to include this in the notebook, since <code>@docs</code> is Documenter syntax that the notebook will not understand. This is a case where we can prepend <code>#md</code> to those lines:</p><pre><code class="language-julia">#md # ```@docs
+# This is also markdown.</code></pre><p>Similarly, Literate version 2.9 adds support for using literal markdown strings, <code>md&quot;&quot;&quot; ... &quot;&quot;&quot;</code>, for the markdown sections, for example</p><pre><code class="language-julia">md&quot;&quot;&quot;
+# Title
+blah blah blah
+&quot;&quot;&quot;</code></pre><p>is rewritten to</p><pre><code class="language-julia"># # Title
+# blah blah blah</code></pre><p>This is not enabled by default – it requires passing <code>mdstrings=true</code>. <code>Literate.markdown</code>/<code>Literate.notebook</code>/<code>Literate.script</code>.</p><h2 id="Filtering-lines"><a class="docs-heading-anchor" href="#Filtering-lines"><strong>2.2.</strong> Filtering lines</a><a id="Filtering-lines-1"></a><a class="docs-heading-anchor-permalink" href="#Filtering-lines" title="Permalink"></a></h2><p>It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of &quot;tokens&quot; that can be used to mark the purpose of certain lines:</p><ul><li><code>#md</code>: line exclusive to markdown output,</li><li><code>#nb</code>: line exclusive to notebook output,</li><li><code>#jl</code>: line exclusive to script output,</li><li><code>#src</code>: line exclusive to the source code and thus filtered out unconditionally.</li></ul><p>Lines <em>starting</em> or <em>ending</em> with one of these tokens are filtered out in the <a href="../pipeline/#Pre-processing">preprocessing step</a>. In addition, for markdown output, lines ending with <code>#hide</code> are filtered out similar to Documenter.jl.</p><div class="admonition is-info"><header class="admonition-header">Difference between `#src` and `#hide`</header><div class="admonition-body"><p><code>#src</code> and <code>#hide</code> are quite similar. The only difference is that <code>#src</code> lines are filtered out <em>before</em> execution (if <code>execute=true</code>) and <code>#hide</code> lines are filtered out <em>after</em> execution.</p></div></div><div class="admonition is-success"><header class="admonition-header">Tip</header><div class="admonition-body"><p>The tokens can also be negated, for example a line starting with <code>#!nb</code> would be included in markdown and script output, but filtered out for notebook output.</p></div></div><p>Suppose, for example, that we want to include a docstring within a <code>@docs</code> block using Documenter. Obviously we don&#39;t want to include this in the notebook, since <code>@docs</code> is Documenter syntax that the notebook will not understand. This is a case where we can prepend <code>#md</code> to those lines:</p><pre><code class="language-julia">#md # ```@docs
 #md # Literate.markdown
 #md # Literate.notebook
-#md # Literate.markdown
+#md # Literate.script
 #md # ```</code></pre><p>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 simply remove the leading <code>#md</code> from the lines. Beware that the space after the tag is also removed.</p><p>The <code>#src</code> token can also be placed at the <em>end</em> 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 <code>@test</code> at the end without this showing up in the outputs:</p><pre><code class="language-julia">using Test                      #src
-@test result == expected_result #src</code></pre><h2 id="Default-replacements"><a class="docs-heading-anchor" href="#Default-replacements"><strong>2.3.</strong> Default replacements</a><a id="Default-replacements-1"></a><a class="docs-heading-anchor-permalink" href="#Default-replacements" title="Permalink"></a></h2><p>The following convenience &quot;macros&quot;/source placeholders are always expanded:</p><ul><li><p><code>@__NAME__</code>:</p><p>expands to the <code>name</code> keyword argument to <a href="../outputformats/#Literate.markdown"><code>Literate.markdown</code></a>, <a href="../outputformats/#Literate.notebook"><code>Literate.notebook</code></a> and <a href="../outputformats/#Literate.script"><code>Literate.script</code></a> (defaults to the filename of the input file).</p></li><li><p><code>@__REPO_ROOT_URL__</code>:</p><p>Can be used to link to files in the repository. For example <code>@__REPO_ROOT_URL__/src/Literate.jl</code> would link to the <a href="https://github.com/fredrikekre/Literate.jl/blob/master/src/Literate.jl">source of the Literate module</a>. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see <a href="../outputformats/#Configuration">Configuration</a>.</p></li><li><p><code>@__NBVIEWER_ROOT_URL__</code>:</p><p>Can be used if you want a link that opens the generated notebook in <a href="http://nbviewer.jupyter.org/">http://nbviewer.jupyter.org/</a>. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see <a href="../outputformats/#Configuration">Configuration</a>.</p></li><li><p><code>@__BINDER_ROOT_URL__</code>:</p><p>Can be used if you want a link that opens the generated notebook in <a href="https://mybinder.org/">https://mybinder.org/</a>. For example, to add a binder-badge in e.g. the HTML output you can use:</p><pre><code class="nohighlight">[![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)</code></pre><p>This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see <a href="../outputformats/#Configuration">Configuration</a>.</p></li></ul></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« <strong>1.</strong> Introduction</a><a class="docs-footer-nextpage" href="../pipeline/"><strong>3.</strong> Processing pipeline »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 01:04">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+@test result == expected_result #src</code></pre><h2 id="Default-replacements"><a class="docs-heading-anchor" href="#Default-replacements"><strong>2.3.</strong> Default replacements</a><a id="Default-replacements-1"></a><a class="docs-heading-anchor-permalink" href="#Default-replacements" title="Permalink"></a></h2><p>The following convenience &quot;macros&quot;/source placeholders are always expanded:</p><ul><li><p><code>@__NAME__</code>:</p><p>expands to the <code>name</code> keyword argument to <a href="../outputformats/#Literate.markdown"><code>Literate.markdown</code></a>, <a href="../outputformats/#Literate.notebook"><code>Literate.notebook</code></a> and <a href="../outputformats/#Literate.script"><code>Literate.script</code></a> (defaults to the filename of the input file).</p></li><li><p><code>@__REPO_ROOT_URL__</code>:</p><p>Can be used to link to files in the repository. For example <code>@__REPO_ROOT_URL__/src/Literate.jl</code> would link to the <a href="https://github.com/fredrikekre/Literate.jl/blob/master/src/Literate.jl">source of the Literate module</a>. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see <a href="../outputformats/#Configuration">Configuration</a>.</p></li><li><p><code>@__NBVIEWER_ROOT_URL__</code>:</p><p>Can be used if you want a link that opens the generated notebook in <a href="http://nbviewer.jupyter.org/">http://nbviewer.jupyter.org/</a>. This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see <a href="../outputformats/#Configuration">Configuration</a>.</p></li><li><p><code>@__BINDER_ROOT_URL__</code>:</p><p>Can be used if you want a link that opens the generated notebook in <a href="https://mybinder.org/">https://mybinder.org/</a>. For example, to add a binder-badge in e.g. the HTML output you can use:</p><pre><code class="nohighlight">[![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)</code></pre><p>This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, but can be configured, see <a href="../outputformats/#Configuration">Configuration</a>.</p></li></ul></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« <strong>1.</strong> Introduction</a><a class="docs-footer-nextpage" href="../pipeline/"><strong>3.</strong> Processing pipeline »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 02:39">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/pipeline/index.html

@@ -29,4 +29,4 @@ x = 1 // 3
 y = 2 // 5</code></pre><p>Chunk #3:</p><pre><code class="language-markdown">When adding `x` and `y` together we obtain a new rational number:</code></pre><p>Chunk #4:</p><pre><code class="language-julia">z = x + y</code></pre><p>It is then up to the <a href="#Document-generation">Document generation</a> step to decide how these chunks should be treated.</p><h3 id="Custom-control-over-chunk-splits"><a class="docs-heading-anchor" href="#Custom-control-over-chunk-splits">Custom control over chunk splits</a><a id="Custom-control-over-chunk-splits-1"></a><a class="docs-heading-anchor-permalink" href="#Custom-control-over-chunk-splits" title="Permalink"></a></h3><p>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 <code>@example</code> blocks or notebook cells. The <code>#-</code> token can be used for this purpose. All lines starting with <code>#-</code> are used as &quot;chunk-splitters&quot;:</p><pre><code class="language-julia">x = 1 // 3
 y = 2 // 5
 #-
-z = x + y</code></pre><p>The example above would result in two consecutive code-chunks.</p><div class="admonition is-success"><header class="admonition-header">Tip</header><div class="admonition-body"><p>The rest of the line, after <code>#-</code>, is discarded, so it is possible to use e.g. <code>#-------------</code> as a chunk splitter, which may make the source code more readable.</p></div></div><p>It is also possible to use <code>#+</code> as a chunk splitter. The difference between <code>#+</code> and <code>#-</code> is that <code>#+</code> enables Documenter&#39;s &quot;continued&quot;-blocks, see the <a href="https://juliadocs.github.io/Documenter.jl/stable/">Documenter manual</a>.</p><h2 id="Document-generation"><a class="docs-heading-anchor" href="#Document-generation"><strong>3.3.</strong> Document generation</a><a id="Document-generation-1"></a><a class="docs-heading-anchor-permalink" href="#Document-generation" title="Permalink"></a></h2><p>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: <a href="@ref">Markdown Output</a>, <a href="@ref">Notebook Output</a> and <a href="@ref">Script Output</a>. Using the default settings, the following is happening:</p><ul><li>Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to <code>@example</code>-blocks),</li><li>Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,</li><li>Script output: markdown chunks are discarded, code chunks are printed as-is.</li></ul><h2 id="Post-processing"><a class="docs-heading-anchor" href="#Post-processing"><strong>3.4.</strong> Post-processing</a><a id="Post-processing-1"></a><a class="docs-heading-anchor-permalink" href="#Post-processing" title="Permalink"></a></h2><p>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 <a href="../customprocessing/#Custom-pre-and-post-processing">Custom pre- and post-processing</a>.</p><h2 id="Writing-to-file"><a class="docs-heading-anchor" href="#Writing-to-file"><strong>3.5.</strong> Writing to file</a><a id="Writing-to-file-1"></a><a class="docs-heading-anchor-permalink" href="#Writing-to-file" title="Permalink"></a></h2><p>The last step of the generation is writing to file. The result is written to <code>$(outputdir)/$(name)(.md|.ipynb|.jl)</code> where <code>outputdir</code> is the output directory supplied by the user (for example <code>docs/generated</code>), and <code>name</code> is a user supplied filename. It is recommended to add the output directory to <code>.gitignore</code> since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../fileformat/">« <strong>2.</strong> File format</a><a class="docs-footer-nextpage" href="../outputformats/"><strong>4.</strong> Output formats »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 01:03">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+z = x + y</code></pre><p>The example above would result in two consecutive code-chunks.</p><div class="admonition is-success"><header class="admonition-header">Tip</header><div class="admonition-body"><p>The rest of the line, after <code>#-</code>, is discarded, so it is possible to use e.g. <code>#-------------</code> as a chunk splitter, which may make the source code more readable.</p></div></div><p>It is also possible to use <code>#+</code> as a chunk splitter. The difference between <code>#+</code> and <code>#-</code> is that <code>#+</code> enables Documenter&#39;s &quot;continued&quot;-blocks, see the <a href="https://juliadocs.github.io/Documenter.jl/stable/">Documenter manual</a>.</p><h2 id="Document-generation"><a class="docs-heading-anchor" href="#Document-generation"><strong>3.3.</strong> Document generation</a><a id="Document-generation-1"></a><a class="docs-heading-anchor-permalink" href="#Document-generation" title="Permalink"></a></h2><p>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: <a href="@ref">Markdown Output</a>, <a href="@ref">Notebook Output</a> and <a href="@ref">Script Output</a>. Using the default settings, the following is happening:</p><ul><li>Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to <code>@example</code>-blocks),</li><li>Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,</li><li>Script output: markdown chunks are discarded, code chunks are printed as-is.</li></ul><h2 id="Post-processing"><a class="docs-heading-anchor" href="#Post-processing"><strong>3.4.</strong> Post-processing</a><a id="Post-processing-1"></a><a class="docs-heading-anchor-permalink" href="#Post-processing" title="Permalink"></a></h2><p>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 <a href="../customprocessing/#Custom-pre-and-post-processing">Custom pre- and post-processing</a>.</p><h2 id="Writing-to-file"><a class="docs-heading-anchor" href="#Writing-to-file"><strong>3.5.</strong> Writing to file</a><a id="Writing-to-file-1"></a><a class="docs-heading-anchor-permalink" href="#Writing-to-file" title="Permalink"></a></h2><p>The last step of the generation is writing to file. The result is written to <code>$(outputdir)/$(name)(.md|.ipynb|.jl)</code> where <code>outputdir</code> is the output directory supplied by the user (for example <code>docs/generated</code>), and <code>name</code> is a user supplied filename. It is recommended to add the output directory to <code>.gitignore</code> since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../fileformat/">« <strong>2.</strong> File format</a><a class="docs-footer-nextpage" href="../outputformats/"><strong>4.</strong> Output formats »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 02:39">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/search/index.html

@@ -1,2 +1,2 @@
 <!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Search · Literate.jl</title><script data-outdated-warner src="../assets/warner.js"></script><link rel="canonical" href="https://fredrikekre.github.io/Literate.jl/v2/search/"/><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.039/juliamono-regular.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.11/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script><link href="../assets/custom.css" rel="stylesheet" type="text/css"/><link href="../assets/favicon.ico" rel="icon" type="image/x-icon"/></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="../"><img src="../assets/logo.png" alt="Literate.jl logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="../">Literate.jl</a></span></div><form class="docs-search" action><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="../"><strong>1.</strong> Introduction</a></li><li><a class="tocitem" href="../fileformat/"><strong>2.</strong> File format</a></li><li><a class="tocitem" href="../pipeline/"><strong>3.</strong> Processing pipeline</a></li><li><a class="tocitem" href="../outputformats/"><strong>4.</strong> Output formats</a></li><li><a class="tocitem" href="../customprocessing/"><strong>5.</strong> Custom pre- and post-processing</a></li><li><a class="tocitem" href="../documenter/"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><a class="tocitem" href="../tips/"><strong>7.</strong> Tips and tricks</a></li><li><a class="tocitem" href="../generated/example/"><strong>8.</strong> Example</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>Search</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Search</a></li></ul></nav><div class="docs-right"><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article><p id="documenter-search-info">Loading search...</p><ul id="documenter-search-results"></ul></article><nav class="docs-footer"><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 01:04">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body><script src="../search_index.js"></script><script src="../assets/search.js"></script></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Search · Literate.jl</title><script data-outdated-warner src="../assets/warner.js"></script><link rel="canonical" href="https://fredrikekre.github.io/Literate.jl/v2/search/"/><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.039/juliamono-regular.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.11/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script><link href="../assets/custom.css" rel="stylesheet" type="text/css"/><link href="../assets/favicon.ico" rel="icon" type="image/x-icon"/></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="../"><img src="../assets/logo.png" alt="Literate.jl logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="../">Literate.jl</a></span></div><form class="docs-search" action><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="../"><strong>1.</strong> Introduction</a></li><li><a class="tocitem" href="../fileformat/"><strong>2.</strong> File format</a></li><li><a class="tocitem" href="../pipeline/"><strong>3.</strong> Processing pipeline</a></li><li><a class="tocitem" href="../outputformats/"><strong>4.</strong> Output formats</a></li><li><a class="tocitem" href="../customprocessing/"><strong>5.</strong> Custom pre- and post-processing</a></li><li><a class="tocitem" href="../documenter/"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><a class="tocitem" href="../tips/"><strong>7.</strong> Tips and tricks</a></li><li><a class="tocitem" href="../generated/example/"><strong>8.</strong> Example</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>Search</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Search</a></li></ul></nav><div class="docs-right"><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article><p id="documenter-search-info">Loading search...</p><ul id="documenter-search-results"></ul></article><nav class="docs-footer"><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 02:39">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body><script src="../search_index.js"></script><script src="../assets/search.js"></script></html>

dev/tips/index.html

@@ -4,4 +4,4 @@ img = plot(...)
 img = DisplayAs.PNG(img)</code></pre><p>This can save some memory, since the image is never captured in e.g. SVG or HTML formats.</p><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>It is best to always let the object be showable as <code>text/plain</code>. This can be achieved by nested calls to <code>DisplayAs</code> output types. For example, to limit an image <code>img</code> to be showable as just <code>image/png</code> and <code>text/plain</code> you can use</p><pre><code class="language-julia">img = plot(...)
 img = DisplayAs.Text(DisplayAs.PNG(img))</code></pre></div></div><h3 id="debug-execution"><a class="docs-heading-anchor" href="#debug-execution">Debugging code execution</a><a id="debug-execution-1"></a><a class="docs-heading-anchor-permalink" href="#debug-execution" title="Permalink"></a></h3><p>When Literate is executing code (i.e. when <code>execute = true</code> is set), it does so quietly. All the output gets captured and nothing gets printed into the terminal. This can make it tricky to know where things go wrong, e.g. when the execution stalls due to an infinite loop.</p><p>To help debug this, Literate has an <code>@debug</code> statement that prints out each code block that is being executed. In general, to enable the printing of Literate&#39;s <code>@debug</code> statements, you can set the <code>JULIA_DEBUG</code> environment variable to <code>&quot;Literate&quot;</code>.</p><p>The easiest way to do that is to set the variable in the Julia session before running Literate by doing</p><pre><code class="language-julia">ENV[&quot;JULIA_DEBUG&quot;]=&quot;Literate&quot;</code></pre><p>Alternatively, you can also set the environment variable before starting the Julia session, e.g.</p><pre><code class="language-sh">$ JULIA_DEBUG=Literate julia</code></pre><p>or by wrapping the Literate calls in an <code>withenv</code> block</p><pre><code class="language-julia">withenv(&quot;JULIA_DEBUG&quot; =&gt; &quot;Literate&quot;) do
     Literate.notebook(&quot;myscript.jl&quot;; execute=true)
-end</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../documenter/">« <strong>6.</strong> Interaction with Documenter.jl</a><a class="docs-footer-nextpage" href="../generated/example/"><strong>8.</strong> Example »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 01:04">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+end</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../documenter/">« <strong>6.</strong> Interaction with Documenter.jl</a><a class="docs-footer-nextpage" href="../generated/example/"><strong>8.</strong> Example »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 02:39">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>