@ -14,4 +14,4 @@ z = x + y</code></pre><p>In the lines starting with <code>#</code> we can use re
@@ -14,4 +14,4 @@ z = x + y</code></pre><p>In the lines starting with <code>#</code> we can use re
#md # Literate.notebook
#md # Literate.markdown
#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 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><codeclass="language-julia">using Test #src
@test result == expected_result #src</code></pre><h2><aclass="nav-anchor"id="Default-Replacements-1"href="#Default-Replacements-1"><strong>2.3.</strong> Default Replacements</a></h2><p>The following convenience "macros" are always expanded:</p><ul><li><p><code>@__NAME__</code></p><p>expands to the <code>name</code> keyword argument to <ahref="../outputformats/#Literate.markdown"><code>Literate.markdown</code></a>, <ahref="../outputformats/#Literate.notebook"><code>Literate.notebook</code></a> and <ahref="../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>expands to <code>https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/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["TRAVIS_REPO_SLUG"])/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 <ahref="http://nbviewer.jupyter.org/">http://nbviewer.jupyter.org/</a>.</p></li></ul><footer><hr/><aclass="previous"href="../"><spanclass="direction">Previous</span><spanclass="title"><strong>1.</strong> Introduction</span></a><aclass="next"href="../pipeline/"><spanclass="direction">Next</span><spanclass="title"><strong>3.</strong> Processing pipeline</span></a></footer></article></body></html>
@test result == expected_result #src</code></pre><h2><aclass="nav-anchor"id="Default-Replacements-1"href="#Default-Replacements-1"><strong>2.3.</strong> Default Replacements</a></h2><p>The following convenience "macros" are always expanded:</p><ul><li><p><code>@__NAME__</code></p><p>expands to the <code>name</code> keyword argument to <ahref="../outputformats/#Literate.markdown"><code>Literate.markdown</code></a>, <ahref="../outputformats/#Literate.notebook"><code>Literate.notebook</code></a> and <ahref="../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>expands to <code>https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/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["TRAVIS_REPO_SLUG"])/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 <ahref="http://nbviewer.jupyter.org/">http://nbviewer.jupyter.org/</a>.</p></li><li><p><code>@__BINDER_ROOT_URL__</code></p><p>expands to <code>https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder)/</code> where <code>branch</code>/<code>folder</code> is the branch and folder where <code>Documenter.deploydocs</code> deploys too. This can be used if you want a link that opens the generated notebook in <ahref="https://mybinder.org/">https://mybinder.org/</a>. To add a binder-badge in e.g. the HTML output you can use:</p><pre><codeclass="language-none">[](@__BINDER_ROOT_URL__path/to/notebook.inpynb)</code></pre></li></ul><footer><hr/><aclass="previous"href="../"><spanclass="direction">Previous</span><spanclass="title"><strong>1.</strong> Introduction</span></a><aclass="next"href="../pipeline/"><spanclass="direction">Next</span><spanclass="title"><strong>3.</strong> Processing pipeline</span></a></footer></article></body></html>
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>7. Example · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL="../.."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="../../assets/documenter.js"></script><scriptsrc="../../siteinfo.js"></script><scriptsrc="../../../versions.js"></script><linkhref="../../assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><ahref="../../index.html"><imgclass="logo"src="../../assets/logo.png"alt="Literate.jl logo"/></a><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="../../search/"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="../../"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="../../fileformat/"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="../../pipeline/"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="../../outputformats/"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="../../customprocessing/"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="../../documenter/"><strong>6.</strong> Interaction with Documenter.jl</a></li><liclass="current"><aclass="toctext"href><strong>7.</strong> Example</a><ulclass="internal"></ul></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref><strong>7.</strong> Example</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>7. Example</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="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: <ahref="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: <ahref="https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/dev/generated/example.ipynb"><code>example.ipynb</code></a>, and the plain script output can be found here: <ahref="../example.jl"><code>example.jl</code></a>.</p><p>It is recommended to have the <ahref="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><aclass="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>#</code> is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:</p><div><pre><codeclass="language-julia">x = 1//3
y = 2//5</code></pre><pre><codeclass="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 <ahref="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 <ahref="../../fileformat/#Filtering-Lines-1">Filtering Lines</a>):</p><ul><li>This line starts with <code>#md</code> and is thus only visible in the markdown output.</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><codeclass="language-julia">x + y</code></pre><pre><codeclass="language-none">11//15</code></pre></div><div><pre><codeclass="language-julia">x * y</code></pre><pre><codeclass="language-none">2//15</code></pre></div><h3><aclass="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><codeclass="language-julia">function foo()
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>7. Example · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL="../.."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="../../assets/documenter.js"></script><scriptsrc="../../siteinfo.js"></script><scriptsrc="../../../versions.js"></script><linkhref="../../assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><ahref="../../index.html"><imgclass="logo"src="../../assets/logo.png"alt="Literate.jl logo"/></a><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="../../search/"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="../../"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="../../fileformat/"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="../../pipeline/"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="../../outputformats/"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="../../customprocessing/"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="../../documenter/"><strong>6.</strong> Interaction with Documenter.jl</a></li><liclass="current"><aclass="toctext"href><strong>7.</strong> Example</a><ulclass="internal"></ul></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref><strong>7.</strong> Example</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>7. Example</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="**7.**-Example-1"href="#**7.**-Example-1"><strong>7.</strong> Example</a></h1><p><ahref="https://mybinder.org/v2/gh/fredrikekre/Literate.jl/gh-pages?filepath=dev/generated/example.inpynb"><imgsrc="https://mybinder.org/badge_logo.svg"alt/></a><ahref="https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/dev/generated/example.ipynb"><imgsrc="https://img.shields.io/badge/show-nbviewer-579ACA.svg"alt/></a></p><p>This is an example generated with Literate based on this source file: <ahref="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 viewed in <ahref="http://nbviewer.jupyter.org/">nbviewer</a> here: <ahref="https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/dev/generated/example.ipynb"><code>example.ipynb</code></a>, and opened in <ahref="https://mybinder.org/">binder</a> here: <ahref="https://mybinder.org/v2/gh/fredrikekre/Literate.jl/gh-pages?filepath=dev/generated/example.ipynb"><code>example.ipynb</code></a>, and the plain script output can be found here: <ahref="../example.jl"><code>example.jl</code></a>.</p><p>It is recommended to have the <ahref="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><aclass="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>#</code> is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:</p><pre><codeclass="language-julia">x = 1//3
y = 2//5</code></pre><pre><codeclass="language-none">2//5</code></pre><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 <ahref="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 <ahref="../../fileformat/#Filtering-Lines-1">Filtering Lines</a>):</p><ul><li>This line starts with <code>#md</code> and is thus only visible in the markdown output.</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><pre><codeclass="language-julia">x + y</code></pre><pre><codeclass="language-none">11//15</code></pre><pre><codeclass="language-julia">x * y</code></pre><pre><codeclass="language-none">2//15</code></pre><h3><aclass="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><pre><codeclass="language-julia">function foo()
println("This string is printed to stdout.")
return [1, 2, 3, 4]
end
foo()</code></pre><pre><codeclass="language-none">This string is printed to stdout.
4</code></pre></div><p>Both Documenter's <code>@example</code> block and notebooks can display images. Here is an example where we generate a simple plot using the <ahref="https://github.com/JuliaPlots/Plots.jl">Plots.jl</a> package</p><div><pre><codeclass="language-julia">using Plots
4</code></pre><p>Both Documenter's <code>@example</code> block and notebooks can display images. Here is an example where we generate a simple plot using the <ahref="https://github.com/JuliaPlots/Plots.jl">Plots.jl</a> package</p><pre><codeclass="language-julia">using Plots
</div><h3><aclass="nav-anchor"id="Custom-processing-1"href="#Custom-processing-1">Custom processing</a></h3><p>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 <code>z</code> and <code>1.0 + 2.0im</code>:</p><div><pre><codeclass="language-julia">z = 1.0 + 2.0im</code></pre><pre><codeclass="language-none">1.0 + 2.0im</code></pre></div><h3><aclass="nav-anchor"id="documenter-interaction-1"href="#documenter-interaction-1">Documenter.jl interaction</a></h3><p>In the source file it is possible to use Documenter.jl style references, such as <code>@ref</code> and <code>@id</code>. These will be filtered out in the notebook output. For example, <ahref="#documenter-interaction-1">here is a link</a>, but it is only visible as a link if you are reading the markdown output. We can also use equations:</p><div>\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]</div><p>using Documenters math syntax. Documenters syntax is automatically changed to <code>\begin{equation} ... \end{equation}</code> in the notebook output to display correctly.</p><p><em>This page was generated using <ahref="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p><footer><hr/><aclass="previous"href="../../documenter/"><spanclass="direction">Previous</span><spanclass="title"><strong>6.</strong> Interaction with Documenter.jl</span></a></footer></article></body></html>
<h3><aclass="nav-anchor"id="Custom-processing-1"href="#Custom-processing-1">Custom processing</a></h3><p>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 <code>z</code> and <code>1.0 + 2.0im</code>:</p><pre><codeclass="language-julia">z = 1.0 + 2.0im</code></pre><pre><codeclass="language-none">1.0 + 2.0im</code></pre><h3><aclass="nav-anchor"id="documenter-interaction-1"href="#documenter-interaction-1">Documenter.jl interaction</a></h3><p>In the source file it is possible to use Documenter.jl style references, such as <code>@ref</code> and <code>@id</code>. These will be filtered out in the notebook output. For example, <ahref="#documenter-interaction-1">here is a link</a>, but it is only visible as a link if you are reading the markdown output. We can also use equations:</p><div>\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]</div><p>using Documenters math syntax. Documenters syntax is automatically changed to <code>\begin{equation} ... \end{equation}</code> in the notebook output to display correctly.</p><p><em>This page was generated using <ahref="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p><footer><hr/><aclass="previous"href="../../documenter/"><spanclass="direction">Previous</span><spanclass="title"><strong>6.</strong> Interaction with Documenter.jl</span></a></footer></article></body></html>
zeptodoctor
7 years ago