build based on ec6a9d3

latest/fileformat.html

@@ -9,8 +9,9 @@ y = 2//5
 
 #' When adding `x` and `y` together we obtain a new rational number:
 
-z = x + y</code></pre><p>In the lines <code>#&#39;</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><p>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).</p></li><li><p>The script is &quot;self-explanatory&quot;, i.e. the markdown lines works as comments and thus serve as good documentation on its own.</p></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><p><code>#md</code>, <code>#nb</code>, <code>#jl</code>: tags for filtering of lines, see <a href="fileformat.html#Filtering-Lines-1">Filtering Lines</a>.</p></li><li><p><code>#-</code>: tag for manually controlling chunk-splits, see <a href="pipeline.html#Custom-control-over-chunk-splits-1">Custom control over chunk splits</a>.</p></li></ul><p>There is also some default convenience replacements that will always be performed, see <a href="fileformat.html#Default-Replacements-1">Default Replacements</a>.</p><h2><a class="nav-anchor" id="Filtering-Lines-1" href="#Filtering-Lines-1"><strong>2.2.</strong> Filtering Lines</a></h2><p>It is possible to filter out lines depending on the output format. For this purpose, there are three different &quot;tokens&quot; that can be placed on the start of the line:</p><ul><li><p><code>#md</code>: markdown output only,</p></li><li><p><code>#nb</code>: notebook output only,</p></li><li><p><code>#jl</code>: script output only.</p></li></ul><p>Lines starting with one of these tokens are filtered out in the <a href="pipeline.html#Pre-processing-1">preprocessing step</a>.</p><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 #&#39; ```@docs
+z = x + y</code></pre><p>In the lines <code>#&#39;</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><p>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).</p></li><li><p>The script is &quot;self-explanatory&quot;, i.e. the markdown lines works as comments and thus serve as good documentation on its own.</p></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><p><code>#md</code>, <code>#nb</code>, <code>#jl</code>, <code>#src</code>: tags to filter lines, see <a href="fileformat.html#Filtering-Lines-1">Filtering Lines</a>,</p></li><li><p><code>#-</code>: tag to manually control chunk-splits, see <a href="pipeline.html#Custom-control-over-chunk-splits-1">Custom control over chunk splits</a>.</p></li></ul><p>There is also some default convenience replacements that will always be performed, see <a href="fileformat.html#Default-Replacements-1">Default Replacements</a>.</p><h2><a class="nav-anchor" id="Filtering-Lines-1" href="#Filtering-Lines-1"><strong>2.2.</strong> Filtering Lines</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><p><code>#md</code>: line exclusive to markdown output,</p></li><li><p><code>#nb</code>: line exclusive to notebook output,</p></li><li><p><code>#jl</code>: line exclusive to script output,</p></li><li><p><code>#src</code>: line exclusive to the source code and thus filtered out unconditionally.</p></li></ul><p>Lines <em>starting</em> with one of these tokens are filtered out in the <a href="pipeline.html#Pre-processing-1">preprocessing step</a>.</p><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 #&#39; ```@docs
 #md #&#39; Literate.markdown
 #md #&#39; Literate.notebook
 #md #&#39; Literate.markdown
-#md #&#39; ```</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 simple remove the leading <code>#md</code> from the lines. Beware that the space after the tag is also removed.</p><h2><a class="nav-anchor" id="Default-Replacements-1" href="#Default-Replacements-1"><strong>2.3.</strong> Default Replacements</a></h2><p>The following convenience &quot;macros&quot; are always expanded:</p><ul><li><p><code>@__NAME__</code></p><p>expands to the <code>name</code> keyword argument to <a href="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>, <a href="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a> and <a href="outputformats.html#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>expands to <code>https://github.com/$(ENV[&quot;TRAVIS_REPO_SLUG&quot;])/blob/master/</code> and is a convenient way to use when you want to link to files outside the doc-build directory. For example <code>@__REPO__ROOT_URL__src/Literate.jl</code> would link to the source of the Literate module.</p></li><li><p><code>@__NBVIEWER_ROOT_URL__</code></p><p>expands to <code>https://nbviewer.jupyter.org/github/$(ENV[&quot;TRAVIS_REPO_SLUG&quot;])/blob/gh-pages/$(folder)/</code> where <code>folder</code> is the folder that <code>Documenter.deploydocs</code> deploys too. This 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>.</p></li></ul><footer><hr/><a class="previous" href="index.html"><span class="direction">Previous</span><span class="title"><strong>1.</strong> Introduction</span></a><a class="next" href="pipeline.html"><span class="direction">Next</span><span class="title"><strong>3.</strong> Processing pipeline</span></a></footer></article></body></html>
+#md #&#39; ```</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 simple 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><a class="nav-anchor" id="Default-Replacements-1" href="#Default-Replacements-1"><strong>2.3.</strong> Default Replacements</a></h2><p>The following convenience &quot;macros&quot; are always expanded:</p><ul><li><p><code>@__NAME__</code></p><p>expands to the <code>name</code> keyword argument to <a href="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>, <a href="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a> and <a href="outputformats.html#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>expands to <code>https://github.com/$(ENV[&quot;TRAVIS_REPO_SLUG&quot;])/blob/master/</code> and is a convenient way to use when you want to link to files outside the doc-build directory. For example <code>@__REPO__ROOT_URL__src/Literate.jl</code> would link to the source of the Literate module.</p></li><li><p><code>@__NBVIEWER_ROOT_URL__</code></p><p>expands to <code>https://nbviewer.jupyter.org/github/$(ENV[&quot;TRAVIS_REPO_SLUG&quot;])/blob/gh-pages/$(folder)/</code> where <code>folder</code> is the folder that <code>Documenter.deploydocs</code> deploys too. This 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>.</p></li></ul><footer><hr/><a class="previous" href="index.html"><span class="direction">Previous</span><span class="title"><strong>1.</strong> Introduction</span></a><a class="next" href="pipeline.html"><span class="direction">Next</span><span class="title"><strong>3.</strong> Processing pipeline</span></a></footer></article></body></html>

latest/generated/example.html

@@ -1,6 +1,6 @@
 <!DOCTYPE html>
 <html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>7. Example · Literate.jl</title><link href="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css" rel="stylesheet" type="text/css"/><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link href="../assets/documenter.css" rel="stylesheet" type="text/css"/></head><body><nav class="toc"><h1>Literate.jl</h1><select id="version-selector" onChange="window.location.href=this.value" style="visibility: hidden"></select><form class="search" id="search-form" action="../search.html"><input id="search-query" name="q" type="text" placeholder="Search docs"/></form><ul><li><a class="toctext" href="../index.html"><strong>1.</strong> Introduction</a></li><li><a class="toctext" href="../fileformat.html"><strong>2.</strong> File Format</a></li><li><a class="toctext" href="../pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><a class="toctext" href="../outputformats.html"><strong>4.</strong> Output Formats</a></li><li><a class="toctext" href="../customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><a class="toctext" href="../documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><li class="current"><a class="toctext" href="example.html"><strong>7.</strong> Example</a><ul class="internal"></ul></li></ul></nav><article id="docs"><header><nav><ul><li><a href="example.html"><strong>7.</strong> Example</a></li></ul><a class="edit-page" href="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl"><span class="fa"></span> Edit on GitHub</a></nav><hr/><div id="topbar"><span>7. Example</span><a class="fa fa-bars" href="#"></a></div></header><h1><a class="nav-anchor" id="**7.**-Example-1" href="#**7.**-Example-1"><strong>7.</strong> Example</a></h1><p>This is an example generated with Literate based on this source file: <a href="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl"><code>example.jl</code></a>. 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: <a href="https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/latest/generated/example.ipynb"><code>example.ipynb</code></a>, and the plain script output can be found here: <a href="example.jl"><code>example.jl</code></a>.</p><p>It is recommended to have the <a href="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl">source file</a> available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.</p><h3><a class="nav-anchor" id="Basic-syntax-1" href="#Basic-syntax-1">Basic syntax</a></h3><p>The basic syntax for Literate is simple, lines starting with <code>#&#39;</code> is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:</p><div><pre><code class="language-julia">x = 1//3
-y = 2//5</code></pre><pre><code class="language-none">2//5</code></pre></div><p>In markdown sections we can use markdown syntax. For example, we can write <em>text in italic font</em>, <strong>text in bold font</strong> and use <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">links</a>.</p><p>It is possible to filter lines by starting it with <code>#md</code>, <code>#nb</code> or <code>#jl</code> for markdown, notebook and script output only, respectively. This line is filtered out for notebook and script output.</p><p>The source file is parsed in chunks of markdown and code. Starting a line with <code>#-</code> manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert <code>#-</code> in between. These two code blocks will now end up in different <code>@example</code>-blocks in the markdown output, and two different notebook cells in the notebook output.</p><div><pre><code class="language-julia">x + y</code></pre><pre><code class="language-none">11//15</code></pre></div><div><pre><code class="language-julia">x * y</code></pre><pre><code class="language-none">2//15</code></pre></div><h3><a class="nav-anchor" id="Output-Capturing-1" href="#Output-Capturing-1">Output Capturing</a></h3><p>Code chunks are by default placed in Documenter <code>@example</code> 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 <code>execute</code> keyword argument is set to true. Output to <code>stdout</code>/<code>stderr</code> is also captured.</p><div><pre><code class="language-julia">function foo()
+y = 2//5</code></pre><pre><code class="language-none">2//5</code></pre></div><p>In markdown sections we can use markdown syntax. For example, we can write <em>text in italic font</em>, <strong>text in bold font</strong> and use <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">links</a>.</p><p>It is possible to filter out lines depending on the output using the <code>#md</code>, <code>#nb</code>, <code>#jl</code> and <code>#src</code> tags (see <a href="../fileformat.html#Filtering-Lines-1">Filtering Lines</a>):</p><ul><li><p>This line starts with <code>#md</code> and is thus only visible in the markdown output.</p></li></ul><p>The source file is parsed in chunks of markdown and code. Starting a line with <code>#-</code> manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert <code>#-</code> in between. These two code blocks will now end up in different <code>@example</code>-blocks in the markdown output, and two different notebook cells in the notebook output.</p><div><pre><code class="language-julia">x + y</code></pre><pre><code class="language-none">11//15</code></pre></div><div><pre><code class="language-julia">x * y</code></pre><pre><code class="language-none">2//15</code></pre></div><h3><a class="nav-anchor" id="Output-Capturing-1" href="#Output-Capturing-1">Output Capturing</a></h3><p>Code chunks are by default placed in Documenter <code>@example</code> 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 <code>execute</code> keyword argument is set to true. Output to <code>stdout</code>/<code>stderr</code> is also captured.</p><div><pre><code class="language-julia">function foo()
     println(&quot;This string is printed to stdout.&quot;)
     return [1, 2, 3, 4]
 end

latest/generated/example.ipynb

@@ -68,9 +68,9 @@
    "outputs": [],
    "cell_type": "markdown",
    "source": [
-    "It is possible to filter lines by starting it with `#md`, `#nb` or `#jl`\n",
+    "It is possible to filter out lines depending on the output using the\n",
-    "for markdown, notebook and script output only, respectively.\n",
+    "`#md`, `#nb`, `#jl` and `#src` tags (see Filtering Lines):\n",
-    "This line is filtered out for markdown and script output."
+    "- This line starts with `#nb` and is thus only visible in the notebook output."
    ],
    "metadata": {}
   },

latest/outputformats.html

@@ -27,7 +27,7 @@ When adding `x` and `y` together we obtain a new rational number:
 
 ```@example name
 z = x + y
-```</code></pre><p>We note that lines starting with <code>#&#39;</code> is printed as regular markdown, and the code lines have been wrapped in <code>@example</code> blocks.</p><p>Some of the output rendering can be controlled with keyword arguments to <a href="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>:</p><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Literate.markdown" href="#Literate.markdown"><code>Literate.markdown</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">Literate.markdown(inputfile, outputdir; kwargs...)</code></pre><p>Generate a markdown file from <code>inputfile</code> and write the result to the directory<code>outputdir</code>.</p><p>Keyword arguments:</p><ul><li><p><code>name</code>: name of the output file, excluding <code>.md</code>. <code>name</code> is also used to name all the <code>@example</code> blocks, and to replace <code>@__NAME__</code>. Defaults to the filename of <code>inputfile</code>.</p></li><li><p><code>preprocess</code>, <code>postprocess</code>: custom pre- and post-processing functions, see the <a href="customprocessing.html#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a> section of the manual. Defaults to <code>identity</code>.</p></li><li><p><code>documenter</code>: boolean that tells if the output is intended to use with Documenter.jl. Defaults to <code>true</code>. See the the manual section on <a href="documenter.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</p></li><li><p><code>codefence</code>: A <code>Pair</code> of opening and closing code fence. Defaults to</p><pre><code class="language-none">&quot;```@example $(name)&quot; =&gt; &quot;```&quot;</code></pre><p>if <code>documenter = true</code> and</p><pre><code class="language-none">&quot;```julia&quot; =&gt; &quot;```&quot;</code></pre><p>if <code>documenter = false</code>.</p></li></ul></div><a class="source-link" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/0d424b6081ef2599ccb1659b947efc76e19a01ab/src/Literate.jl#L269-L294">source</a></section><h2><a class="nav-anchor" id="Notebook-Output-1" href="#Notebook-Output-1"><strong>4.2.</strong> Notebook Output</a></h2><p>The (default) notebook output of the source snippet above is as follows</p><pre><code class="language-none">        │ # Rational numbers
+```</code></pre><p>We note that lines starting with <code>#&#39;</code> is printed as regular markdown, and the code lines have been wrapped in <code>@example</code> blocks.</p><p>Some of the output rendering can be controlled with keyword arguments to <a href="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>:</p><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Literate.markdown" href="#Literate.markdown"><code>Literate.markdown</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">Literate.markdown(inputfile, outputdir; kwargs...)</code></pre><p>Generate a markdown file from <code>inputfile</code> and write the result to the directory<code>outputdir</code>.</p><p>Keyword arguments:</p><ul><li><p><code>name</code>: name of the output file, excluding <code>.md</code>. <code>name</code> is also used to name all the <code>@example</code> blocks, and to replace <code>@__NAME__</code>. Defaults to the filename of <code>inputfile</code>.</p></li><li><p><code>preprocess</code>, <code>postprocess</code>: custom pre- and post-processing functions, see the <a href="customprocessing.html#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a> section of the manual. Defaults to <code>identity</code>.</p></li><li><p><code>documenter</code>: boolean that tells if the output is intended to use with Documenter.jl. Defaults to <code>true</code>. See the the manual section on <a href="documenter.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</p></li><li><p><code>codefence</code>: A <code>Pair</code> of opening and closing code fence. Defaults to</p><pre><code class="language-none">&quot;```@example $(name)&quot; =&gt; &quot;```&quot;</code></pre><p>if <code>documenter = true</code> and</p><pre><code class="language-none">&quot;```julia&quot; =&gt; &quot;```&quot;</code></pre><p>if <code>documenter = false</code>.</p></li></ul></div><a class="source-link" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/ec6a9d31dfd2679d01b8a074d56a2e6091c0c5f1/src/Literate.jl#L270-L295">source</a></section><h2><a class="nav-anchor" id="Notebook-Output-1" href="#Notebook-Output-1"><strong>4.2.</strong> Notebook Output</a></h2><p>The (default) notebook output of the source snippet above is as follows</p><pre><code class="language-none">        │ # Rational numbers
         │
         │ In julia rational numbers can be constructed with the `//` operator.
         │ Lets define two rational numbers, `x` and `y`:
@@ -41,8 +41,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</code></pre><p>We note that lines starting with <code>#&#39;</code> 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 <a href="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a>:</p><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Literate.notebook" href="#Literate.notebook"><code>Literate.notebook</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">Literate.notebook(inputfile, outputdir; kwargs...)</code></pre><p>Generate a notebook from <code>inputfile</code> and write the result to <code>outputdir</code>.</p><p>Keyword arguments:</p><ul><li><p><code>name</code>: name of the output file, excluding <code>.ipynb</code>. <code>name</code> is also used to replace <code>@__NAME__</code>. Defaults to the filename of <code>inputfile</code>.</p></li><li><p><code>preprocess</code>, <code>postprocess</code>: custom pre- and post-processing functions, see the <a href="customprocessing.html#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a> section of the manual. Defaults to <code>identity</code>.</p></li><li><p><code>execute</code>: a boolean deciding if the generated notebook should also be executed or not. Defaults to <code>true</code>. The current working directory is set to <code>outputdir</code> when executing the notebook.</p></li><li><p><code>documenter</code>: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to <code>true</code>. See the the manual section on <a href="documenter.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</p></li></ul></div><a class="source-link" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/0d424b6081ef2599ccb1659b947efc76e19a01ab/src/Literate.jl#L365-L382">source</a></section><h2><a class="nav-anchor" id="Script-Output-1" href="#Script-Output-1"><strong>4.3.</strong> Script Output</a></h2><p>The (default) script output of the source snippet above is as follows</p><pre><code class="language-julia">x = 1//3
+Out[3]: │ 11/15</code></pre><p>We note that lines starting with <code>#&#39;</code> 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 <a href="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a>:</p><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Literate.notebook" href="#Literate.notebook"><code>Literate.notebook</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">Literate.notebook(inputfile, outputdir; kwargs...)</code></pre><p>Generate a notebook from <code>inputfile</code> and write the result to <code>outputdir</code>.</p><p>Keyword arguments:</p><ul><li><p><code>name</code>: name of the output file, excluding <code>.ipynb</code>. <code>name</code> is also used to replace <code>@__NAME__</code>. Defaults to the filename of <code>inputfile</code>.</p></li><li><p><code>preprocess</code>, <code>postprocess</code>: custom pre- and post-processing functions, see the <a href="customprocessing.html#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a> section of the manual. Defaults to <code>identity</code>.</p></li><li><p><code>execute</code>: a boolean deciding if the generated notebook should also be executed or not. Defaults to <code>true</code>. The current working directory is set to <code>outputdir</code> when executing the notebook.</p></li><li><p><code>documenter</code>: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to <code>true</code>. See the the manual section on <a href="documenter.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</p></li></ul></div><a class="source-link" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/ec6a9d31dfd2679d01b8a074d56a2e6091c0c5f1/src/Literate.jl#L366-L383">source</a></section><h2><a class="nav-anchor" id="Script-Output-1" href="#Script-Output-1"><strong>4.3.</strong> Script Output</a></h2><p>The (default) script output of the source snippet above is as follows</p><pre><code class="language-julia">x = 1//3
 
 y = 2//5
 
-z = x + y</code></pre><p>We note that lines starting with <code>#&#39;</code> are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to <a href="outputformats.html#Literate.script"><code>Literate.script</code></a>:</p><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Literate.script" href="#Literate.script"><code>Literate.script</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">Literate.script(inputfile, outputdir; kwargs...)</code></pre><p>Generate a plain script file from <code>inputfile</code> and write the result to <code>outputdir</code>.</p><p>Keyword arguments:</p><ul><li><p><code>name</code>: name of the output file, excluding <code>.jl</code>. <code>name</code> is also used to replace <code>@__NAME__</code>. Defaults to the filename of <code>inputfile</code>.</p></li><li><p><code>preprocess</code>, <code>postprocess</code>: custom pre- and post-processing functions, see the <a href="customprocessing.html#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a> section of the manual. Defaults to <code>identity</code>.</p></li><li><p><code>documenter</code>: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to <code>true</code>. See the the manual section on <a href="documenter.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</p></li><li><p><code>keep_comments</code>: boolean that, if set to <code>true</code>, keeps markdown lines (<code>#&#39;</code>) as comments in the output script. Defaults to <code>false</code>.</p></li></ul></div><a class="source-link" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/0d424b6081ef2599ccb1659b947efc76e19a01ab/src/Literate.jl#L205-L221">source</a></section><footer><hr/><a class="previous" href="pipeline.html"><span class="direction">Previous</span><span class="title"><strong>3.</strong> Processing pipeline</span></a><a class="next" href="customprocessing.html"><span class="direction">Next</span><span class="title"><strong>5.</strong> Custom pre- and post-processing</span></a></footer></article></body></html>
+z = x + y</code></pre><p>We note that lines starting with <code>#&#39;</code> are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to <a href="outputformats.html#Literate.script"><code>Literate.script</code></a>:</p><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="Literate.script" href="#Literate.script"><code>Literate.script</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">Literate.script(inputfile, outputdir; kwargs...)</code></pre><p>Generate a plain script file from <code>inputfile</code> and write the result to <code>outputdir</code>.</p><p>Keyword arguments:</p><ul><li><p><code>name</code>: name of the output file, excluding <code>.jl</code>. <code>name</code> is also used to replace <code>@__NAME__</code>. Defaults to the filename of <code>inputfile</code>.</p></li><li><p><code>preprocess</code>, <code>postprocess</code>: custom pre- and post-processing functions, see the <a href="customprocessing.html#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a> section of the manual. Defaults to <code>identity</code>.</p></li><li><p><code>documenter</code>: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to <code>true</code>. See the the manual section on <a href="documenter.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</p></li><li><p><code>keep_comments</code>: boolean that, if set to <code>true</code>, keeps markdown lines (<code>#&#39;</code>) as comments in the output script. Defaults to <code>false</code>.</p></li></ul></div><a class="source-link" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/ec6a9d31dfd2679d01b8a074d56a2e6091c0c5f1/src/Literate.jl#L206-L222">source</a></section><footer><hr/><a class="previous" href="pipeline.html"><span class="direction">Previous</span><span class="title"><strong>3.</strong> Processing pipeline</span></a><a class="next" href="customprocessing.html"><span class="direction">Next</span><span class="title"><strong>5.</strong> Custom pre- and post-processing</span></a></footer></article></body></html>

latest/search_index.js

@@ -53,7 +53,7 @@ var documenterSearchIndex = {"docs": [
     "page": "2. File Format",
     "title": "2.1. Syntax",
     "category": "section",
-    "text": "The basic syntax is simple:lines starting with #\' is treated as markdown,\nall 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\n#\'\n#\' In julia rational numbers can be constructed with the `//` operator.\n#\' Lets define two rational numbers, `x` and `y`:\n\nx = 1//3\ny = 2//5\n\n#\' When adding `x` and `y` together we obtain a new rational number:\n\nz = x + yIn 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).\nThe 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:#md, #nb, #jl: tags for filtering of lines, see Filtering Lines.\n#-: tag for manually controlling chunk-splits, see Custom control over chunk splits.There is also some default convenience replacements that will always be performed, see Default Replacements."
+    "text": "The basic syntax is simple:lines starting with #\' is treated as markdown,\nall 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\n#\'\n#\' In julia rational numbers can be constructed with the `//` operator.\n#\' Lets define two rational numbers, `x` and `y`:\n\nx = 1//3\ny = 2//5\n\n#\' When adding `x` and `y` together we obtain a new rational number:\n\nz = x + yIn 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).\nThe 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:#md, #nb, #jl, #src: tags to filter lines, see Filtering Lines,\n#-: tag to manually control chunk-splits, see Custom control over chunk splits.There is also some default convenience replacements that will always be performed, see Default Replacements."
 },
 
 {
@@ -61,7 +61,7 @@ var documenterSearchIndex = {"docs": [
     "page": "2. File Format",
     "title": "2.2. Filtering Lines",
     "category": "section",
-    "text": "It is possible to filter out lines depending on the output format. For this purpose, there are three different \"tokens\" that can be placed on the start of the line:#md: markdown output only,\n#nb: notebook output only,\n#jl: script output only.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\n#md #\' Literate.markdown\n#md #\' Literate.notebook\n#md #\' Literate.markdown\n#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."
+    "text": "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,\n#nb: line exclusive to notebook output,\n#jl: line exclusive to script output,\n#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\n#md #\' Literate.markdown\n#md #\' Literate.notebook\n#md #\' Literate.markdown\n#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\n@test result == expected_result #src"
 },
 
 {
@@ -277,7 +277,7 @@ var documenterSearchIndex = {"docs": [
     "page": "7. Example",
     "title": "Basic syntax",
     "category": "section",
-    "text": "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\ny = 2//5In 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 lines by starting it with #md, #nb or #jl for markdown, notebook and script output only, respectively. This line is filtered out for notebook and script 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 + yx * y"
+    "text": "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\ny = 2//5In 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 + yx * y"
 },
 
 {