<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>6. Interaction with Documenter.jl · 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"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><liclass="current"><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a><ulclass="internal"></ul></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/documenter.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>6. Interaction with Documenter.jl</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="Interaction-with-Documenter-1"href="#Interaction-with-Documenter-1"><strong>6.</strong> Interaction with Documenter.jl</a></h1><p>Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (<ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>, <ahref="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a> and <ahref="outputformats.html#Literate.script"><code>Literate.script</code></a>) supports a keyword argument <code>documenter</code> that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set <code>documenter = true</code>:</p><h3><aclass="nav-anchor"id="[Literate.markdown](@ref):-1"href="#[Literate.markdown](@ref):-1"><ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>:</a></h3><ul><li><p>The default code fence will change from</p><pre><codeclass="language-none">```julia
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>6. Interaction with Documenter.jl · 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"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><liclass="current"><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a><ulclass="internal"></ul></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/documenter.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>6. Interaction with Documenter.jl</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="Interaction-with-Documenter-1"href="#Interaction-with-Documenter-1"><strong>6.</strong> Interaction with Documenter.jl</a></h1><p>Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (<ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>, <ahref="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a> and <ahref="outputformats.html#Literate.script"><code>Literate.script</code></a>) supports a keyword argument <code>documenter</code> that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set <code>documenter = true</code>:</p><h3><aclass="nav-anchor"id="[Literate.markdown](@ref):-1"href="#[Literate.markdown](@ref):-1"><ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>:</a></h3><ul><li>The default code fence will change from<pre><codeclass="language-none">```julia
```</code></pre></li><li><p>The following <code>@meta</code> block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the <em>source file</em> rather than the generated <code>.md</code> file:</p><pre><codeclass="language-none">```@meta
```</code></pre></li><li>The following <code>@meta</code> block will be added to the top of the markdown page, which redirects the "Edit on GitHub" link on the top of the page to the <em>source file</em> rather than the generated <code>.md</code> file:<pre><codeclass="language-none">```@meta
```</code></pre></li></ul><h3><aclass="nav-anchor"id="[Literate.notebook](@ref):-1"href="#[Literate.notebook](@ref):-1"><ahref="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a>:</a></h3><ul><li><p>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 notebook.</p></li><li><p>Documenter style markdown math</p><pre><codeclass="language-none">```math
```</code></pre></li></ul><h3><aclass="nav-anchor"id="[Literate.notebook](@ref):-1"href="#[Literate.notebook](@ref):-1"><ahref="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a>:</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 notebook.</li><li>Documenter style markdown math<pre><codeclass="language-none">```math
\int f dx
\int f dx
```</code></pre><p>is replaced with notebook compatible</p><pre><codeclass="language-none">\begin{equation}
```</code></pre>is replaced with notebook compatible<pre><codeclass="language-none">\begin{equation}
\int f dx
\int f dx
\end{equation}</code></pre></li></ul><h3><aclass="nav-anchor"id="[Literate.script](@ref):-1"href="#[Literate.script](@ref):-1"><ahref="outputformats.html#Literate.script"><code>Literate.script</code></a>:</a></h3><ul><li><p>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.</p></li></ul><footer><hr/><aclass="previous"href="customprocessing.html"><spanclass="direction">Previous</span><spanclass="title"><strong>5.</strong> Custom pre- and post-processing</span></a><aclass="next"href="generated/example.html"><spanclass="direction">Next</span><spanclass="title"><strong>7.</strong> Example</span></a></footer></article></body></html>
\end{equation}</code></pre></li></ul><h3><aclass="nav-anchor"id="[Literate.script](@ref):-1"href="#[Literate.script](@ref):-1"><ahref="outputformats.html#Literate.script"><code>Literate.script</code></a>:</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><footer><hr/><aclass="previous"href="customprocessing.html"><spanclass="direction">Previous</span><spanclass="title"><strong>5.</strong> Custom pre- and post-processing</span></a><aclass="next"href="generated/example.html"><spanclass="direction">Next</span><spanclass="title"><strong>7.</strong> Example</span></a></footer></article></body></html>
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>2. File Format · 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"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><liclass="current"><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a><ulclass="internal"><li><aclass="toctext"href="#Syntax-1"><strong>2.1.</strong> Syntax</a></li><li><aclass="toctext"href="#Filtering-Lines-1"><strong>2.2.</strong> Filtering Lines</a></li><li><aclass="toctext"href="#Default-Replacements-1"><strong>2.3.</strong> Default Replacements</a></li></ul></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="fileformat.html"><strong>2.</strong> File Format</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/fileformat.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>2. File Format</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="**2.**-File-Format-1"href="#**2.**-File-Format-1"><strong>2.</strong> File Format</a></h1><p>The source file format for Literate is a regular, commented, julia (<code>.jl</code>) scripts. The idea is that the scripts also serve as documentation on their own and it is also simple to include them in the test-suite, with e.g. <code>include</code>, to make sure the examples stay up do date with other changes in your package.</p><h2><aclass="nav-anchor"id="Syntax-1"href="#Syntax-1"><strong>2.1.</strong> Syntax</a></h2><p>The basic syntax is simple:</p><ul><li><p>lines starting with <code>#</code> are treated as markdown,</p></li><li><p>all other lines are treated as julia code.</p></li></ul><p>Leading whitespace is allowed before <code>#</code>, but it will be removed when generating the output. Since <code>#</code>-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use <code>##</code>, which will render as <code>#</code> in the output.</p><p>Lets look at a simple example:</p><pre><codeclass="language-julia"># # Rational numbers
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>2. File Format · 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"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><liclass="current"><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a><ulclass="internal"><li><aclass="toctext"href="#Syntax-1"><strong>2.1.</strong> Syntax</a></li><li><aclass="toctext"href="#Filtering-Lines-1"><strong>2.2.</strong> Filtering Lines</a></li><li><aclass="toctext"href="#Default-Replacements-1"><strong>2.3.</strong> Default Replacements</a></li></ul></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="fileformat.html"><strong>2.</strong> File Format</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/fileformat.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>2. File Format</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="**2.**-File-Format-1"href="#**2.**-File-Format-1"><strong>2.</strong> File Format</a></h1><p>The source file format for Literate is a regular, commented, julia (<code>.jl</code>) scripts. The idea is that the scripts also serve as documentation on their own and it is also simple to include them in the test-suite, with e.g. <code>include</code>, to make sure the examples stay up do date with other changes in your package.</p><h2><aclass="nav-anchor"id="Syntax-1"href="#Syntax-1"><strong>2.1.</strong> Syntax</a></h2><p>The basic syntax is simple:</p><ul><li>lines starting with <code>#</code> are treated as markdown,</li><li>all other lines are treated as julia code.</li></ul><p>Leading whitespace is allowed before <code>#</code>, but it will be removed when generating the output. Since <code>#</code>-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use <code>##</code>, which will render as <code>#</code> in the output.</p><p>Lets look at a simple example:</p><pre><codeclass="language-julia"># # Rational numbers
#
#
# In julia rational numbers can be constructed with the `//` operator.
# In julia rational numbers can be constructed with the `//` operator.
# Lets define two rational numbers, `x` and `y`:
# Lets define two rational numbers, `x` and `y`:
@ -9,7 +9,7 @@ y = 2//5
# When adding `x` and `y` together we obtain a new rational number:
# When adding `x` and `y` together we obtain a new rational number:
z = x + y</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><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 "self-explanatory", 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 <ahref="fileformat.html#Filtering-Lines-1">Filtering Lines</a>,</p></li><li><p><code>#-</code>: tag to manually control chunk-splits, see <ahref="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 <ahref="fileformat.html#Default-Replacements-1">Default Replacements</a>.</p><h2><aclass="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 "tokens" 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 <ahref="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'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><codeclass="language-julia">#md # ```@docs
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 "self-explanatory", 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 <ahref="fileformat.html#Filtering-Lines-1">Filtering Lines</a>,</li><li><code>#-</code>: tag to manually control chunk-splits, see <ahref="pipeline.html#Custom-control-over-chunk-splits-1">Custom control over chunk splits</a>.</li></ul><p>There is also some default convenience replacements that will always be performed, see <ahref="fileformat.html#Default-Replacements-1">Default Replacements</a>.</p><h2><aclass="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 "tokens" 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> with one of these tokens are filtered out in the <ahref="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'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><codeclass="language-julia">#md # ```@docs
<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"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="../search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="../index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="../fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="../pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="../outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="../customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="../documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><liclass="current"><aclass="toctext"href="example.html"><strong>7.</strong> Example</a><ulclass="internal"></ul></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="example.html"><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/latest/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
<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"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="../search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="../index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="../fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="../pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="../outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="../customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="../documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><liclass="current"><aclass="toctext"href="example.html"><strong>7.</strong> Example</a><ulclass="internal"></ul></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="example.html"><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/latest/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.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><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()
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.html#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()
println("This string is printed to stdout.")
println("This string is printed to stdout.")
return [1, 2, 3, 4]
return [1, 2, 3, 4]
end
end
@ -11,332 +11,341 @@ foo()</code></pre><pre><code class="language-none">This string is printed to std
2
2
3
3
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></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
@ -149,7 +149,7 @@ var documenterSearchIndex = {"docs": [
"page":"4. Output Formats",
"page":"4. Output Formats",
"title":"4. Output Formats",
"title":"4. Output Formats",
"category":"section",
"category":"section",
"text":"When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:Markdown.parse(\"```julia\\n\" * rstrip(read(\"outputformats.jl\", String)) * \"\\n```\")and see how this is rendered in each of the output formats."
"text":"When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:import Markdown\nMarkdown.parse(\"```julia\\n\" * rstrip(read(\"outputformats.jl\", String)) * \"\\n```\")and see how this is rendered in each of the output formats."
},
},
{
{
@ -157,7 +157,7 @@ var documenterSearchIndex = {"docs": [
"page":"4. Output Formats",
"page":"4. Output Formats",
"title":"Literate.markdown",
"title":"Literate.markdown",
"category":"function",
"category":"function",
"text":"Literate.markdown(inputfile, outputdir; kwargs...)\n\nGenerate a markdown file from inputfile and write the result to the directoryoutputdir.\n\nKeyword arguments:\n\nname: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.\npreprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.\ndocumenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.\ncodefence: A Pair of opening and closing code fence. Defaults to\n\"```@example $(name)\" => \"```\"\nif documenter = true and\n\"```julia\" => \"```\"\nif documenter = false.\n\n\n\n"
"text":"Literate.markdown(inputfile, outputdir; kwargs...)\n\nGenerate a markdown file from inputfile and write the result to the directoryoutputdir.\n\nKeyword arguments:\n\nname: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.\npreprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.\ndocumenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.\ncodefence: A Pair of opening and closing code fence. Defaults to\n\"```@example $(name)\" => \"```\"\nif documenter = true and\n\"```julia\" => \"```\"\nif documenter = false.\n\n\n\n\n\n"
},
},
{
{
@ -165,7 +165,7 @@ var documenterSearchIndex = {"docs": [
"page":"4. Output Formats",
"page":"4. Output Formats",
"title":"4.1. Markdown Output",
"title":"4.1. Markdown Output",
"category":"section",
"category":"section",
"text":"The (default) markdown output of the source snippet above is as followsfile = joinpath(@__DIR__, \"src/generated/name.md\")\nstr = \"````markdown\\n\" * rstrip(read(file, String)) * \"\\n````\"\nrm(file)\nMarkdown.parse(str)We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the \"Edit on GitHub\" link for the page, see Interaction with Documenter.Some of the output rendering can be controlled with keyword arguments to Literate.markdown:Literate.markdown"
"text":"The (default) markdown output of the source snippet above is as followsimport Markdown\nfile = joinpath(@__DIR__, \"../src/generated/name.md\")\nstr = \"````markdown\\n\" * rstrip(read(file, String)) * \"\\n````\"\nrm(file)\nMarkdown.parse(str)We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the \"Edit on GitHub\" link for the page, see Interaction with Documenter.Some of the output rendering can be controlled with keyword arguments to Literate.markdown:Literate.markdown"
},
},
{
{
@ -173,7 +173,7 @@ var documenterSearchIndex = {"docs": [
"page":"4. Output Formats",
"page":"4. Output Formats",
"title":"Literate.notebook",
"title":"Literate.notebook",
"category":"function",
"category":"function",
"text":"Literate.notebook(inputfile, outputdir; kwargs...)\n\nGenerate a notebook from inputfile and write the result to outputdir.\n\nKeyword arguments:\n\nname: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.\npreprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.\nexecute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.\ndocumenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.\n\n\n\n"
"text":"Literate.notebook(inputfile, outputdir; kwargs...)\n\nGenerate a notebook from inputfile and write the result to outputdir.\n\nKeyword arguments:\n\nname: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.\npreprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.\nexecute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.\ndocumenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.\n\n\n\n\n\n"
},
},
{
{
@ -189,7 +189,7 @@ var documenterSearchIndex = {"docs": [
"page":"4. Output Formats",
"page":"4. Output Formats",
"title":"Literate.script",
"title":"Literate.script",
"category":"function",
"category":"function",
"text":"Literate.script(inputfile, outputdir; kwargs...)\n\nGenerate a plain script file from inputfile and write the result to outputdir.\n\nKeyword arguments:\n\nname: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.\npreprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.\ndocumenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.\nkeep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.\n\n\n\n"
"text":"Literate.script(inputfile, outputdir; kwargs...)\n\nGenerate a plain script file from inputfile and write the result to outputdir.\n\nKeyword arguments:\n\nname: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.\npreprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.\ndocumenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.\nkeep_comments: boolean that, if set to true, keeps markdown lines as comments in the output script. Defaults to false.\n\n\n\n\n\n"
},
},
{
{
@ -197,7 +197,7 @@ var documenterSearchIndex = {"docs": [
"page":"4. Output Formats",
"page":"4. Output Formats",
"title":"4.3. Script Output",
"title":"4.3. Script Output",
"category":"section",
"category":"section",
"text":"The (default) script output of the source snippet above is as followsfile = joinpath(@__DIR__, \"src/generated/outputformats.jl\")\nstr = \"```julia\\n\" * rstrip(read(file, String)) * \"\\n```\"\nrm(file)\nMarkdown.parse(str)We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:Literate.script"
"text":"The (default) script output of the source snippet above is as followsimport Markdown\nfile = joinpath(@__DIR__, \"../src/generated/outputformats.jl\")\nstr = \"```julia\\n\" * rstrip(read(file, String)) * \"\\n```\"\nrm(file)\nMarkdown.parse(str)We note that lines starting with # are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:Literate.script"
},
},
{
{
@ -285,7 +285,7 @@ var documenterSearchIndex = {"docs": [
"page":"7. Example",
"page":"7. Example",
"title":"Output Capturing",
"title":"Output Capturing",
"category":"section",
"category":"section",
"text":"Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.function foo()\n println(\"This string is printed to stdout.\")\n return [1, 2, 3, 4]\nend\n\nfoo()Both Documenter\'s @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl packageusing Plots\nx = linspace(0, 6π, 1000)\ny1 = sin.(x)\ny2 = cos.(x)\nplot(x, [y1, y2])"
"text":"Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.function foo()\n println(\"This string is printed to stdout.\")\n return [1, 2, 3, 4]\nend\n\nfoo()Both Documenter\'s @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl packageusing Plots\nx = range(0, stop=6π, length=1000)\ny1 = sin.(x)\ny2 = cos.(x)\nplot(x, [y1, y2])"
autodocs
8 years ago