|
|
<!DOCTYPE html> |
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>2. File Format · 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://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="../"><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/"><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 class="is-active"><a class="tocitem" href><strong>2.</strong> File Format</a><ul class="internal"><li><a class="tocitem" href="#Syntax-1"><span><strong>2.1.</strong> Syntax</span></a></li><li><a class="tocitem" href="#Filtering-Lines-1"><span><strong>2.2.</strong> Filtering Lines</span></a></li><li><a class="tocitem" href="#Default-Replacements-1"><span><strong>2.3.</strong> Default Replacements</span></a></li></ul></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><a class="tocitem" href="../generated/example/"><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><strong>2.</strong> File Format</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href><strong>2.</strong> File Format</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/fileformat.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="**2.**-File-Format-1"><strong>2.</strong> File Format<a class="docs-heading-anchor" href="#**2.**-File-Format-1" title="Permalink"></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 id="Syntax-1"><strong>2.1.</strong> Syntax<a class="docs-heading-anchor" href="#Syntax-1" title="Permalink"></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><code class="language-julia"># # Rational numbers |
|
|
# |
|
|
# In julia rational numbers can be constructed with the `//` operator. |
|
|
# Lets define two rational numbers, `x` and `y`: |
|
|
|
|
|
## Define variable 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>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 <a href="#Filtering-Lines-1">Filtering Lines</a>,</li><li><code>#-</code> (<code>#+</code>): tag to manually control chunk-splits, see <a href="../pipeline/#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 <a href="#Default-Replacements-1">Default Replacements</a>.</p><h2 id="Filtering-Lines-1"><strong>2.2.</strong> Filtering Lines<a class="docs-heading-anchor" href="#Filtering-Lines-1" title="Permalink"></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 <a href="../pipeline/#Pre-processing-1">preprocessing step</a>.</p><div class="admonition is-success"><header class="admonition-header">Tip</header><div class="admonition-body"><p>The tokens can also be negated, for example a line starting with <code>#!nb</code> would be included in markdown and script output, but filtered out for notebook output.</p></div></div><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><code class="language-julia">#md # ```@docs |
|
|
#md # Literate.markdown |
|
|
#md # Literate.notebook |
|
|
#md # Literate.markdown |
|
|
#md # ```</code></pre><p>The lines in the example above would be filtered out in the preprocessing step, unless we are generating a markdown file. When generating a markdown file we would simple remove the leading <code>#md</code> from the lines. Beware that the space after the tag is also removed.</p><p>The <code>#src</code> token can also be placed at the <em>end</em> of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a <code>@test</code> at the end without this showing up in the outputs:</p><pre><code class="language-julia">using Test #src |
|
|
@test result == expected_result #src</code></pre><h2 id="Default-Replacements-1"><strong>2.3.</strong> Default Replacements<a class="docs-heading-anchor" href="#Default-Replacements-1" title="Permalink"></a></h2><p>The following convenience "macros" are always expanded:</p><ul><li><p><code>@__NAME__</code></p><p>expands to the <code>name</code> keyword argument to <a href="../outputformats/#Literate.markdown"><code>Literate.markdown</code></a>, <a href="../outputformats/#Literate.notebook"><code>Literate.notebook</code></a> and <a href="../outputformats/#Literate.script"><code>Literate.script</code></a> (defaults to the filename of the input file).</p></li><li><p><code>@__REPO_ROOT_URL__</code></p><p>expands to <code>https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master</code> and is a convenient way to use when you want to link to files outside the doc-build directory. For example <code>@__REPO_ROOT_URL__/src/Literate.jl</code> would link to the source of the Literate module.</p></li><li><p><code>@__NBVIEWER_ROOT_URL__</code></p><p>expands to <code>https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)</code> where <code>folder</code> is the folder that <code>Documenter.deploydocs</code> deploys too. This can be used if you want a link that opens the generated notebook in <a href="http://nbviewer.jupyter.org/">http://nbviewer.jupyter.org/</a>.</p></li><li><p><code>@__BINDER_ROOT_URL__</code></p><p>expands to <code>https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder)</code> where <code>branch</code>/<code>folder</code> is the branch and folder where <code>Documenter.deploydocs</code> deploys too. This can be used if you want a link that opens the generated notebook in <a href="https://mybinder.org/">https://mybinder.org/</a>. To add a binder-badge in e.g. the HTML output you can use:</p><pre><code class="language-none">[](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)</code></pre></li></ul><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p><code>@__REPO_ROOT_URL__</code> and <code>@__NBVIEWER_ROOT_URL__</code> works for documentation built with <a href="https://github.com/JuliaDocs/DocumentationGenerator.jl">DocumentationGenerator.jl</a> but <code>@__BINDER_ROOT_URL__</code> does not, since <code>mybinder.org</code> requires the files to be located inside a git repository.</p></div></div></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« <strong>1.</strong> Introduction</a><a class="docs-footer-nextpage" href="../pipeline/"><strong>3.</strong> Processing pipeline »</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="Thursday 21 November 2019 12:18">Thursday 21 November 2019</span>. Using Julia version 1.2.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
|
|
|
|
