|
|
<!DOCTYPE html> |
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>7. Tips and tricks · Literate.jl</title><script data-outdated-warner src="../assets/warner.js"></script><link rel="canonical" href="https://fredrikekre.github.io/Literate.jl/v2/tips/"/><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.039/juliamono-regular.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.11/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script><link href="../assets/custom.css" rel="stylesheet" type="text/css"/><link href="../assets/favicon.ico" rel="icon" type="image/x-icon"/></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="../"><img src="../assets/logo.png" alt="Literate.jl logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="../">Literate.jl</a></span></div><form class="docs-search" action="../search/"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="../"><strong>1.</strong> Introduction</a></li><li><a class="tocitem" href="../fileformat/"><strong>2.</strong> File format</a></li><li><a class="tocitem" href="../pipeline/"><strong>3.</strong> Processing pipeline</a></li><li><a class="tocitem" href="../outputformats/"><strong>4.</strong> Output formats</a></li><li><a class="tocitem" href="../customprocessing/"><strong>5.</strong> Custom pre- and post-processing</a></li><li><a class="tocitem" href="../documenter/"><strong>6.</strong> Interaction with Documenter.jl</a></li><li class="is-active"><a class="tocitem" href><strong>7.</strong> Tips and tricks</a></li><li><a class="tocitem" href="../generated/example/"><strong>8.</strong> Example</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href><strong>7.</strong> Tips and tricks</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href><strong>7.</strong> Tips and tricks</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/tips.md" title="Edit on GitHub"><span class="docs-icon fab"></span><span class="docs-label is-hidden-touch">Edit on GitHub</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="tips-and-tricks"><a class="docs-heading-anchor" href="#tips-and-tricks"><strong>7.</strong> Tips and tricks</a><a id="tips-and-tricks-1"></a><a class="docs-heading-anchor-permalink" href="#tips-and-tricks" title="Permalink"></a></h1><p>This section lists some tips and tricks that might be useful for using Literate.</p><h3 id="notebook-filesize"><a class="docs-heading-anchor" href="#notebook-filesize">Filesize of generated notebooks</a><a id="notebook-filesize-1"></a><a class="docs-heading-anchor-permalink" href="#notebook-filesize" title="Permalink"></a></h3><p>When Literate executes a notebook the return value, i.e. the result of the last Julia expression in each cell is captured. By default Literate generates multiple renderings of the result in different output formats or <a href="https://en.wikipedia.org/wiki/MIME">MIME</a>s, just like <a href="https://github.com/JuliaLang/IJulia.jl">IJulia.jl</a> does. All of these renderings are embedded in the notebook and it is up to the notebook frontend viewer to select the most appropriate format to show to the user.</p><p>A common example is images, which can often be displayed in multiple formats, e.g. PNG (<code>image/png</code>), SVG (<code>image/svg+xml</code>) and HTML (<code>text/html</code>). As a result, the filesize of the generated notebook can become large.</p><p>In order to remedy this you can use the clever Julia package <a href="https://github.com/tkf/DisplayAs.jl"><code>DisplayAs</code></a> to limit the output capabilities of an object. For example, to "force" an image to be captures as <code>image/png</code> only, you can use</p><pre><code class="language-julia">import DisplayAs |
|
|
img = plot(...) |
|
|
img = DisplayAs.PNG(img)</code></pre><p>This can save some memory, since the image is never captured in e.g. SVG or HTML formats.</p><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>It is best to always let the object be showable as <code>text/plain</code>. This can be achieved by nested calls to <code>DisplayAs</code> output types. For example, to limit an image <code>img</code> to be showable as just <code>image/png</code> and <code>text/plain</code> you can use</p><pre><code class="language-julia">img = plot(...) |
|
|
img = DisplayAs.Text(DisplayAs.PNG(img))</code></pre></div></div><h3 id="admonitions-md"><a class="docs-heading-anchor" href="#admonitions-md">Adding admonitions using compound line filtering</a><a id="admonitions-md-1"></a><a class="docs-heading-anchor-permalink" href="#admonitions-md" title="Permalink"></a></h3><p>Admonitions are a useful feature for drawing attention to particular elements of documentation. They are <a href="https://juliadocs.github.io/Documenter.jl/stable/showcase/#Basic-Markdown">documented in Documenter.jl</a> and an example of their use can be seen above in the blue 'note' box. Admonitions is a specific Julia markdown feature, and they are not recognized by either common mark or Jupyter notebooks. The <code>md</code> line filter can be used to make sure admonitions only show up in markdown output, for example:</p><pre><code class="nohighlight">#md # !!! note "Be aware!" |
|
|
#md # This a note style admonition!</code></pre><p>It is important to note that both <code>#md</code> and the second <code>#</code> are required. Literate.jl interprets the first <code>#md</code> as a markdown exclusive line, and then strips it out. The second <code>#</code> tells Literate.jl that the line should be parsed as markdown and not a Julia code block. If you only include <code>#md</code> and not the second <code>#</code> then it will be parsed into Julia example block in the final documentation and not an actual admonition.</p><h3 id="admonitions-compatibility"><a class="docs-heading-anchor" href="#admonitions-compatibility">Custom parsing for markdown and notebook compatible admonitions</a><a id="admonitions-compatibility-1"></a><a class="docs-heading-anchor-permalink" href="#admonitions-compatibility" title="Permalink"></a></h3><p>As mentioned above, admonitions are not compatible with Jupyter notebooks. (Though at time of writing this documentation, <a href="https://github.com/jupyter/notebook/issues/1292">this is an open issue in Jupyter</a> so may change in the future.) For now, we can write a custom preprocessor function so that admonitions are interpreted as quotes (with their own special formatting) in notebooks and proper admonitions in markdown. For the case of note admonitions, this can be written as follows:</p><pre><code class="language-julia">function md_note(str) |
|
|
str = replace(str, r"^#note # (.*)$"m => s""" |
|
|
# !!! note |
|
|
# \1""") |
|
|
return str |
|
|
end |
|
|
|
|
|
function nb_note(str) |
|
|
str = replace(str, r"^#note # (.*)$"m => s""" |
|
|
# > *Note* |
|
|
# > \1""") |
|
|
return str |
|
|
end |
|
|
|
|
|
using Literate |
|
|
|
|
|
Literate.markdown("example.jl", "tmp/"; preprocess = md_note) |
|
|
|
|
|
Literate.notebook("example.jl", "tmp/"; preprocess = nb_note)</code></pre><p>This will allow us to turn the following source code in <code>example.jl</code>:</p><pre><code class="language-julia">#note # This is a useful note.</code></pre><p>into the correct admonition syntax in the markdown file generated:</p><pre><code class="language-julia">!!! note |
|
|
This is a useful note.</code></pre><p>and a quotation style formatting in the generated notebook cell:</p><pre><code class="language-julia">> *Note* |
|
|
> This is a useful note.</code></pre><p>which, in an actual notebook cell, will look similar to:</p><blockquote><p><em>Note</em><br/>This is a useful note.</p></blockquote><h3 id="debug-execution"><a class="docs-heading-anchor" href="#debug-execution">Debugging code execution</a><a id="debug-execution-1"></a><a class="docs-heading-anchor-permalink" href="#debug-execution" title="Permalink"></a></h3><p>When Literate is executing code (i.e. when <code>execute = true</code> is set), it does so quietly. All the output gets captured and nothing gets printed into the terminal. This can make it tricky to know where things go wrong, e.g. when the execution stalls due to an infinite loop.</p><p>To help debug this, Literate has an <code>@debug</code> statement that prints out each code block that is being executed. In general, to enable the printing of Literate's <code>@debug</code> statements, you can set the <code>JULIA_DEBUG</code> environment variable to <code>"Literate"</code>.</p><p>The easiest way to do that is to set the variable in the Julia session before running Literate by doing</p><pre><code class="language-julia">ENV["JULIA_DEBUG"]="Literate"</code></pre><p>Alternatively, you can also set the environment variable before starting the Julia session, e.g.</p><pre><code class="language-sh">$ JULIA_DEBUG=Literate julia</code></pre><p>or by wrapping the Literate calls in an <code>withenv</code> block</p><pre><code class="language-julia">withenv("JULIA_DEBUG" => "Literate") do |
|
|
Literate.notebook("myscript.jl"; execute=true) |
|
|
end</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../documenter/">« <strong>6.</strong> Interaction with Documenter.jl</a><a class="docs-footer-nextpage" href="../generated/example/"><strong>8.</strong> Example »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.3 on <span class="colophon-date" title="Friday 9 July 2021 08:50">Friday 9 July 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
|
|
|
|
