|
|
<!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><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.8.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.8.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.8.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css" rel="stylesheet" type="text/css"/><link href="https://cdn.jsdelivr.net/npm/katex@0.10.2/dist/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link href="assets/custom.css" rel="stylesheet" type="text/css"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-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></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Literate.jl logo"/></a><div class="docs-package-name"><span class="docs-autofit">Literate.jl</span></div><form class="docs-search" action="search.html"><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="index.html"><strong>1.</strong> Introduction</a></li><li><a class="tocitem" href="fileformat.html"><strong>2.</strong> File Format</a></li><li><a class="tocitem" href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li class="is-active"><a class="tocitem" href="outputformats.html"><strong>4.</strong> Output Formats</a><ul class="internal"><li><a class="tocitem" href="#Markdown-Output-1"><span><strong>4.1.</strong> Markdown Output</span></a></li><li><a class="tocitem" href="#Notebook-Output-1"><span><strong>4.2.</strong> Notebook Output</span></a></li><li><a class="tocitem" href="#Script-Output-1"><span><strong>4.3.</strong> Script Output</span></a></li></ul></li><li><a class="tocitem" href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><a class="tocitem" href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><a class="tocitem" href="generated/example.html"><strong>7.</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="outputformats.html"><strong>4.</strong> Output Formats</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="outputformats.html"><strong>4.</strong> Output Formats</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/outputformats.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="Output-Formats-1"><strong>4.</strong> Output Formats<a class="docs-heading-anchor" href="#Output-Formats-1" title="Permalink"></a></h1><p>When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:</p><pre><code class="language-julia"># # 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-1"><strong>4.1.</strong> Markdown Output<a class="docs-heading-anchor" href="#Markdown-Output-1" title="Permalink"></a></h2><p>The (default) markdown output of the source snippet above is as follows</p><pre><code class="language-markdown">```@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.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</p><p>Some of the output rendering can be controlled with keyword arguments to <a href="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>:</p><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">Literate.markdown(inputfile, outputdir; kwargs...)</code></pre><p>Generate a markdown file from <code>inputfile</code> and write the result to the directory <code>outputdir</code>.</p><p>Keyword arguments:</p><ul><li><code>name</code>: name of the output file, excluding <code>.md</code>; <code>name</code> is also used to name all the <code>@example</code> blocks, and to replace <code>@__NAME__</code>. Defaults to the filename of <code>inputfile</code>.</li><li><code>preprocess</code>, <code>postprocess</code>: custom pre- and post-processing functions, see the <a href="customprocessing.html#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a> section of the manual. Defaults to <code>identity</code>.</li><li><code>documenter</code>: boolean that tells if the output is intended to use with Documenter.jl. Defaults to <code>true</code>. See the manual section on <a href="documenter.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</li><li><code>codefence</code>: A <code>Pair</code> of opening and closing code fence. Defaults to<pre><code class="language-none">"```@example $(name)" => "```"</code></pre>if <code>documenter = true</code> and<pre><code class="language-none">"```julia" => "```"</code></pre>if <code>documenter = false</code>.</li><li><code>credit</code>: boolean that controls 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 to the default, which is <code>true</code>.</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/75e60f0e256a6ad9da5462fb515018b953538461/src/Literate.jl#L320-L348">source</a></section></article><h2 id="Notebook-Output-1"><strong>4.2.</strong> Notebook Output<a class="docs-heading-anchor" href="#Notebook-Output-1" title="Permalink"></a></h2><p>The (default) notebook output of the source snippet can be seen here: <a href="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. Some of the output rendering can be controlled with keyword arguments to <a href="outputformats.html#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">Literate.notebook(inputfile, outputdir; kwargs...)</code></pre><p>Generate a notebook from <code>inputfile</code> and write the result to <code>outputdir</code>.</p><p>Keyword arguments:</p><ul><li><code>name</code>: name of the output file, excluding <code>.ipynb</code>. <code>name</code> is also used to replace <code>@__NAME__</code>. Defaults to the filename of <code>inputfile</code>.</li><li><code>preprocess</code>, <code>postprocess</code>: custom pre- and post-processing functions, see the <a href="customprocessing.html#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a> section of the manual. Defaults to <code>identity</code>.</li><li><code>execute</code>: a boolean deciding if the generated notebook should also be executed or not. Defaults to <code>true</code>. The current working directory is set to <code>outputdir</code> when executing the notebook.</li><li><code>documenter</code>: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to <code>true</code>. See the the manual section on <a href="documenter.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</li><li><code>credit</code>: boolean that controls 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 to the default, which is <code>true</code>.</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/75e60f0e256a6ad9da5462fb515018b953538461/src/Literate.jl#L447-L467">source</a></section></article><h3 id="Notebook-metadata-1">Notebook metadata<a class="docs-heading-anchor" href="#Notebook-metadata-1" 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="language-none">%% 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><h2 id="Script-Output-1"><strong>4.3.</strong> Script Output<a class="docs-heading-anchor" href="#Script-Output-1" title="Permalink"></a></h2><p>The (default) script output of the source snippet above is as follows</p><pre><code class="language-julia">x = 1//3 |
|
|
|
|
|
y = 2//5 |
|
|
|
|
|
z = x + y</code></pre><p>We note that lines starting with <code>#</code> are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to <a href="outputformats.html#Literate.script"><code>Literate.script</code></a>:</p><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">Literate.script(inputfile, outputdir; kwargs...)</code></pre><p>Generate a plain script file from <code>inputfile</code> and write the result to <code>outputdir</code>.</p><p>Keyword arguments:</p><ul><li><code>name</code>: name of the output file, excluding <code>.jl</code>. <code>name</code> is also used to replace <code>@__NAME__</code>. Defaults to the filename of <code>inputfile</code>.</li><li><code>preprocess</code>, <code>postprocess</code>: custom pre- and post-processing functions, see the <a href="customprocessing.html#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a> section of the manual. Defaults to <code>identity</code>.</li><li><code>documenter</code>: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to <code>true</code>. See the the manual section on <a href="documenter.html#Interaction-with-Documenter-1">Interaction with Documenter</a>.</li><li><code>keep_comments</code>: boolean that, if set to <code>true</code>, keeps markdown lines as comments in the output script. Defaults to <code>false</code>.</li><li><code>credit</code>: boolean that controls 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 to the default, which is <code>true</code>.</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://github.com/fredrikekre/Literate.jl/blob/75e60f0e256a6ad9da5462fb515018b953538461/src/Literate.jl#L250-L269">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="pipeline.html">« <strong>3.</strong> Processing pipeline</a><a class="docs-footer-nextpage" href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing »</a></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> on <span class="colophon-date" title="Saturday 16 November 2019 03:01">Saturday 16 November 2019</span>. Using Julia version 1.2.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
|
|
|
|
