|
|
<!DOCTYPE html> |
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>4. Output formats · Literate.jl</title><script data-outdated-warner src="../assets/warner.js"></script><link rel="canonical" href="https://fredrikekre.github.io/Literate.jl/v2/outputformats/"/><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.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/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 class="is-active"><a class="tocitem" href><strong>4.</strong> Output formats</a><ul class="internal"><li><a class="tocitem" href="#Markdown-output"><span><strong>4.1.</strong> Markdown output</span></a></li><li><a class="tocitem" href="#Notebook-output"><span><strong>4.2.</strong> Notebook output</span></a></li><li><a class="tocitem" href="#Script-output"><span><strong>4.3.</strong> Script output</span></a></li><li><a class="tocitem" href="#Configuration"><span><strong>4.4.</strong> Configuration</span></a></li></ul></li><li><a class="tocitem" href="../customprocessing/"><strong>5.</strong> Custom pre- and post-processing</a></li><li><a class="tocitem" href="../documenter/"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><a class="tocitem" href="../tips/"><strong>7.</strong> Tips and tricks</a></li><li><a class="tocitem" href="../generated/example/"><strong>8.</strong> Example</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href><strong>4.</strong> Output formats</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href><strong>4.</strong> Output formats</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/fredrikekre/Literate.jl" title="View the repository on GitHub"><span class="docs-icon fab"></span><span class="docs-label is-hidden-touch">GitHub</span></a><a class="docs-navbar-link" href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.md" title="Edit source on GitHub"><span class="docs-icon fas"></span></a><a class="docs-settings-button docs-navbar-link fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button docs-navbar-link fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Output-formats"><a class="docs-heading-anchor" href="#Output-formats"><strong>4.</strong> Output formats</a><a id="Output-formats-1"></a><a class="docs-heading-anchor-permalink" href="#Output-formats" title="Permalink"></a></h1><p>When the source is parsed, and has been processed it is time to render the output. We will consider the following source snippet:</p><pre><code class="language-julia hljs"># # Rational numbers |
|
|
# |
|
|
# In julia rational numbers can be constructed with the `//` operator. |
|
|
# Lets define two rational numbers, `x` and `y`: |
|
|
|
|
|
x = 1//3 |
|
|
#- |
|
|
y = 2//5 |
|
|
|
|
|
# When adding `x` and `y` together we obtain a new rational number: |
|
|
|
|
|
z = x + y</code></pre><p>and see how this is rendered in each of the output formats.</p><h2 id="Markdown-output"><a class="docs-heading-anchor" href="#Markdown-output"><strong>4.1.</strong> Markdown output</a><a id="Markdown-output-1"></a><a class="docs-heading-anchor-permalink" href="#Markdown-output" title="Permalink"></a></h2><p>Markdown output is generated by <a href="#Literate.markdown"><code>Literate.markdown</code></a>. There exist various "flavors" of markdown and Literate supports some different flavors, see <a href="#Markdown-flavors">Markdown flavors</a>. The default flavor is <code>Literate.DocumenterFlavor()</code> and, as the name suggest, it generates markdown files meant to be used together with <a href="https://juliadocs.github.io/Documenter.jl">Documenter.jl</a>. The output of the source snippet above is as follows:</p><pre><code class="language-markdown hljs">```@meta |
|
|
EditURL = "https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.jl" |
|
|
``` |
|
|
|
|
|
# Rational numbers |
|
|
|
|
|
In julia rational numbers can be constructed with the `//` operator. |
|
|
Lets define two rational numbers, `x` and `y`: |
|
|
|
|
|
````@example name |
|
|
x = 1//3 |
|
|
```` |
|
|
|
|
|
````@example name |
|
|
y = 2//5 |
|
|
```` |
|
|
|
|
|
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>#</code> are printed as regular markdown, and the code lines have been wrapped in <code>@example</code> blocks. We also note that an <code>@meta</code> block have been added, that sets the <code>EditURL</code> variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see <a href="../documenter/#Interaction-with-Documenter">Interaction with Documenter</a>.</p><p>The <code>@example</code> blocks are wrapped in 4 consecutive backticks so as to allow for docstrings containing triple backticks, for example:</p><pre><code class="language-julia hljs">""" |
|
|
This function perform the following calculation: |
|
|
```math |
|
|
x_1 + x_2 |
|
|
``` |
|
|
""" |
|
|
f(x) = x[1] + x[2]</code></pre><p>If your Julia code itself contains 4 consecutive backticks, you can use the keyword argument <code>codefence</code> to setup 5 backticks for code blocks, see <a href="#Configuration">Configuration</a>.</p><p>It possible to configure <code>Literate.markdown</code> to also evaluate code snippets, capture the result and include it in the output, by passing <code>execute=true</code> as a keyword argument. The result of the first code-block in the example above would then become</p><pre><code class="language-markdown hljs">````julia |
|
|
x = 1//3 |
|
|
```` |
|
|
```` |
|
|
1//3 |
|
|
````</code></pre><p>In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (image/png or image/jpeg), HTML (text/html) or markdown (text/markdown) Literate will include the richest representation of the output.</p><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>Since Documenter executes and captures results of <code>@example</code> block it is not necessary to use <code>execute=true</code> for markdown output that is meant to be used as input to Documenter.</p></div></div><p>See the section about <a href="#Configuration">Configuration</a> for more information about how to configure the behavior and resulting output of <a href="#Literate.markdown"><code>Literate.markdown</code></a>.</p><article class="docstring"><header><a class="docstring-binding" id="Literate.markdown" href="#Literate.markdown"><code>Literate.markdown</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">Literate.markdown(inputfile, outputdir=pwd(); config::AbstractDict=Dict(), kwargs...)</code></pre><p>Generate a markdown file from <code>inputfile</code> and write the result to the directory <code>outputdir</code>.</p><p>See the manual section on <a href="#Configuration">Configuration</a> for documentation of possible configuration with <code>config</code> and other keyword arguments.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/b7ee4af4bc7beca4e1fd5d6497dcfdaacaf6a045/src/Literate.jl#L539-L547">source</a></section></article><h3 id="Markdown-flavors"><a class="docs-heading-anchor" href="#Markdown-flavors">Markdown flavors</a><a id="Markdown-flavors-1"></a><a class="docs-heading-anchor-permalink" href="#Markdown-flavors" title="Permalink"></a></h3><p>Literate can output markdown in different flavors. The flavor is specified using the <code>flavor</code> keyword argument. The following flavors are currently supported:</p><ul><li><code>flavor = Literate.DocumenterFlavor()</code>: this is the default flavor and the output is meant to be used as input to <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a>.</li><li><code>flavor = Literate.CommonMarkFlavor()</code>: this outputs markdown that has the flavor of the <a href="https://commonmark.org/">CommonMark</a> specification.</li><li><code>flavor = Literate.FranklinFlavor()</code>: this outputs markdown meant to be used as input to <a href="https://franklinjl.org/">Franklin.jl</a>.</li></ul><h2 id="Notebook-output"><a class="docs-heading-anchor" href="#Notebook-output"><strong>4.2.</strong> Notebook output</a><a id="Notebook-output-1"></a><a class="docs-heading-anchor-permalink" href="#Notebook-output" title="Permalink"></a></h2><p>Notebook output is generated by <a href="#Literate.notebook"><code>Literate.notebook</code></a>. The (default) notebook output of the source snippet can be seen here: <a href="https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/dev/generated/notebook.ipynb">notebook.ipynb</a>.</p><p>We note that lines starting with <code>#</code> are placed in markdown cells, and the code lines have been placed 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.</p><p>See the section about <a href="#Configuration">Configuration</a> for how to configure the behavior and resulting output of <a href="#Literate.notebook"><code>Literate.notebook</code></a>.</p><article class="docstring"><header><a class="docstring-binding" id="Literate.notebook" href="#Literate.notebook"><code>Literate.notebook</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">Literate.notebook(inputfile, outputdir=pwd(); config::AbstractDict=Dict(), kwargs...)</code></pre><p>Generate a notebook from <code>inputfile</code> and write the result to <code>outputdir</code>.</p><p>See the manual section on <a href="#Configuration">Configuration</a> for documentation of possible configuration with <code>config</code> and other keyword arguments.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/b7ee4af4bc7beca4e1fd5d6497dcfdaacaf6a045/src/Literate.jl#L666-L673">source</a></section></article><h3 id="Notebook-metadata"><a class="docs-heading-anchor" href="#Notebook-metadata">Notebook metadata</a><a id="Notebook-metadata-1"></a><a class="docs-heading-anchor-permalink" href="#Notebook-metadata" title="Permalink"></a></h3><p>Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the <code>%%</code> token, similar to <a href="https://jupytext.readthedocs.io/en/latest/formats.html#the-percent-format">Jupytext</a>. The format is as follows</p><pre><code class="nohighlight hljs">%% optional ignored text [type] {optional metadata JSON}</code></pre><p>Cell metadata can, for example, be used for <a href="https://nbgrader.readthedocs.io/en/stable/contributor_guide/metadata.html">nbgrader</a> and the <a href="https://github.com/hakimel/reveal.js">reveal.js</a> notebook extension <a href="https://github.com/damianavila/RISE">RISE</a>.</p><p>The following would create a 3 slide deck with RISE:</p><pre><code class="language-julia hljs">#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} |
|
|
# # Some title |
|
|
# |
|
|
# We're using `#nb` so the metadata is only included in notebook output |
|
|
|
|
|
#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}} |
|
|
x = 1//3 |
|
|
y = 2//5 |
|
|
|
|
|
#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}} |
|
|
# For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)</code></pre><h2 id="Script-output"><a class="docs-heading-anchor" href="#Script-output"><strong>4.3.</strong> Script output</a><a id="Script-output-1"></a><a class="docs-heading-anchor-permalink" href="#Script-output" title="Permalink"></a></h2><p>Script output is generated by <a href="#Literate.script"><code>Literate.script</code></a>. The (default) script output of the source snippet above is as follows:</p><pre><code class="language-julia hljs">x = 1//3 |
|
|
|
|
|
y = 2//5 |
|
|
|
|
|
z = x + y</code></pre><p>We note that lines starting with <code>#</code> are removed and only the code lines have been kept.</p><p>See the section about <a href="#Configuration">Configuration</a> for how to configure the behavior and resulting output of <a href="#Literate.script"><code>Literate.script</code></a>.</p><article class="docstring"><header><a class="docstring-binding" id="Literate.script" href="#Literate.script"><code>Literate.script</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">Literate.script(inputfile, outputdir=pwd(); config::AbstractDict=Dict(), kwargs...)</code></pre><p>Generate a plain script file from <code>inputfile</code> and write the result to <code>outputdir</code>.</p><p>See the manual section on <a href="#Configuration">Configuration</a> for documentation of possible configuration with <code>config</code> and other keyword arguments.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/b7ee4af4bc7beca4e1fd5d6497dcfdaacaf6a045/src/Literate.jl#L501-L508">source</a></section></article><h2 id="Configuration"><a class="docs-heading-anchor" href="#Configuration"><strong>4.4.</strong> Configuration</a><a id="Configuration-1"></a><a class="docs-heading-anchor-permalink" href="#Configuration" title="Permalink"></a></h2><p>The behavior of <a href="#Literate.markdown"><code>Literate.markdown</code></a>, <a href="#Literate.notebook"><code>Literate.notebook</code></a> and <a href="#Literate.script"><code>Literate.script</code></a> can be configured by keyword arguments. There are two ways to do this; pass <code>config::Dict</code> as a keyword argument, or pass individual keyword arguments.</p><div class="admonition is-info"><header class="admonition-header">Configuration precedence</header><div class="admonition-body"><p>Individual keyword arguments take precedence over the <code>config</code> dictionary, so for e.g. <code>Literate.markdown(...; config = Dict("name" => "hello"), name = "world")</code> the resulting configuration for <code>name</code> will be <code>"world"</code>. Both individual keyword arguments and the <code>config</code> dictionary take precedence over the default.</p></div></div><p>Available configurations with description and default values are given in the reference for <a href="#Literate.DEFAULT_CONFIGURATION"><code>Literate.DEFAULT_CONFIGURATION</code></a> just below.</p><article class="docstring"><header><a class="docstring-binding" id="Literate.DEFAULT_CONFIGURATION" href="#Literate.DEFAULT_CONFIGURATION"><code>Literate.DEFAULT_CONFIGURATION</code></a> — <span class="docstring-category">Constant</span></header><section><div><pre><code class="language-julia hljs">DEFAULT_CONFIGURATION</code></pre><p>Default configuration for <a href="#Literate.markdown"><code>Literate.markdown</code></a>, <a href="#Literate.notebook"><code>Literate.notebook</code></a> and <a href="#Literate.script"><code>Literate.script</code></a> which is used for everything not specified by the user. Configuration can be passed as individual keyword arguments or as a dictionary passed with the <code>config</code> keyword argument. See the manual section about <a href="#Configuration">Configuration</a> for more information.</p><p>Available options:</p><ul><li><code>name</code> (default: <code>filename(inputfile)</code>): Name of the output file (excluding the file extension).</li><li><code>preprocess</code> (default: <code>identity</code>): Custom preprocessing function mapping a <code>String</code> to a <code>String</code>. See <a href="../customprocessing/#Custom-pre-and-post-processing">Custom pre- and post-processing</a>.</li><li><code>postprocess</code> (default: <code>identity</code>): Custom preprocessing function mapping a <code>String</code> to a <code>String</code>. See <a href="../customprocessing/#Custom-pre-and-post-processing">Custom pre- and post-processing</a>.</li><li><code>credit</code> (default: <code>true</code>): Boolean for controlling the addition of <code>This file was generated with Literate.jl ...</code> to the bottom of the page. If you find Literate.jl useful then feel free to keep this.</li><li><code>keep_comments</code> (default: <code>false</code>): When <code>true</code>, keeps markdown lines as comments in the output script. Only applicable for <code>Literate.script</code>.</li><li><code>execute</code> (default: <code>true</code> for notebook, <code>false</code> for markdown): Whether to execute and capture the output. Only applicable for <code>Literate.notebook</code> and <code>Literate.markdown</code>.</li><li><code>codefence</code> (default: <code>"````@example $(name)" => "````"</code> for <code>DocumenterFlavor()</code> and <code>"````julia" => "````"</code> otherwise): Pair containing opening and closing code fence for wrapping code blocks.</li><li><code>flavor</code> (default: <code>Literate.DocumenterFlavor()</code>) Output flavor for markdown, see <a href="#Markdown-flavors">Markdown flavors</a>. Only applicable for <code>Literate.markdown</code>.</li><li><code>devurl</code> (default: <code>"dev"</code>): URL for "in-development" docs, see <a href="https://juliadocs.github.io/Documenter.jl/">Documenter docs</a>. Unused if <code>repo_root_url</code>/ <code>nbviewer_root_url</code>/<code>binder_root_url</code> are set.</li><li><code>repo_root_url</code>: URL to the root of the repository. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for <code>@__REPO_ROOT_URL__</code>.</li><li><code>nbviewer_root_url</code>: URL to the root of the repository as seen on nbviewer. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for <code>@__NBVIEWER_ROOT_URL__</code>.</li><li><code>binder_root_url</code>: URL to the root of the repository as seen on mybinder. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for <code>@__BINDER_ROOT_URL__</code>.</li><li><code>repo_root_path</code>: Filepath to the root of the repository. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing <a href="../documenter/#Interaction-with-Documenter">Documenters <code>EditURL</code></a>.</li><li><code>image_formats</code>: A vector of <code>(mime, ext)</code> tuples, with the default <code>Tuple{MIME, String}[(MIME type image/svg+xml, ".svg"), (MIME type image/png, ".png"), (MIME type image/jpeg, ".jpeg")]</code>. Results which are <code>showable</code> with a MIME type are saved with the first match, with the corresponding extension.</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/b7ee4af4bc7beca4e1fd5d6497dcfdaacaf6a045/src/Literate.jl#L386-L432">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../pipeline/">« <strong>3.</strong> Processing pipeline</a><a class="docs-footer-nextpage" href="../customprocessing/"><strong>5.</strong> Custom pre- and post-processing »</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.28.0-DEV on <span class="colophon-date" title="Monday 13 March 2023 11:14">Monday 13 March 2023</span>. Using Julia version 1.8.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
|
|
|
|
