|
|
<!DOCTYPE html> |
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>5. Custom pre- and post-processing · Literate.jl</title><meta name="title" content="5. Custom pre- and post-processing · Literate.jl"/><meta property="og:title" content="5. Custom pre- and post-processing · Literate.jl"/><meta property="twitter:title" content="5. Custom pre- and post-processing · Literate.jl"/><meta name="description" content="Documentation for Literate.jl."/><meta property="og:description" content="Documentation for Literate.jl."/><meta property="twitter:description" content="Documentation for Literate.jl."/><meta property="og:url" content="https://fredrikekre.github.io/Literate.jl/v2/customprocessing/"/><meta property="twitter:url" content="https://fredrikekre.github.io/Literate.jl/v2/customprocessing/"/><link rel="canonical" href="https://fredrikekre.github.io/Literate.jl/v2/customprocessing/"/><script data-outdated-warner src="../assets/warner.js"></script><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.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/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="../search_index.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/catppuccin-mocha.css" data-theme-name="catppuccin-mocha"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-macchiato.css" data-theme-name="catppuccin-macchiato"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-frappe.css" data-theme-name="catppuccin-frappe"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-latte.css" data-theme-name="catppuccin-latte"/><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><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><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 class="is-active"><a class="tocitem" href><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><li><a class="tocitem" href="../changelog/"><strong>9.</strong> Changelog</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"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href><strong>5.</strong> Custom pre- and post-processing</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href><strong>5.</strong> Custom pre- and post-processing</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 fa-brands"></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/customprocessing.md" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="Custom-pre-and-post-processing"><a class="docs-heading-anchor" href="#Custom-pre-and-post-processing"><strong>5.</strong> Custom pre- and post-processing</a><a id="Custom-pre-and-post-processing-1"></a><a class="docs-heading-anchor-permalink" href="#Custom-pre-and-post-processing" title="Permalink"></a></h1><p>Since all packages are different, and may have different demands on how to create a nice example for the documentation it is important that the package maintainer does not feel limited by the by default provided syntax that this package offers. While you can generally come a long way by utilizing <a href="../fileformat/#Filtering-lines">line filtering</a> there might be situations where you need to manually hook into the generation and change things. In Literate this is done by letting the user supply custom pre- and post-processing functions that may do transformation of the content.</p><p>All of the generators (<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>) accept <code>preprocess</code> and <code>postprocess</code> keyword arguments. The default "transformation" is the <code>identity</code> function. The input to the transformation functions is a <code>String</code>, and the output should be the transformed <code>String</code>.</p><p><code>preprocess</code> is sent the raw input that is read from the source file (<a href="../pipeline/#Pre-processing">modulo the default line ending transformation</a>). <code>postprocess</code> is given different things depending on the output: For markdown and script output <code>postprocess</code> is given the content <code>String</code> just before writing it to the output file, but for notebook output <code>postprocess</code> is given the dictionary representing the notebook, since, in general, this is more useful.</p><h3 id="Example:-Adding-current-date"><a class="docs-heading-anchor" href="#Example:-Adding-current-date">Example: Adding current date</a><a id="Example:-Adding-current-date-1"></a><a class="docs-heading-anchor-permalink" href="#Example:-Adding-current-date" title="Permalink"></a></h3><p>As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a <code>preprocess</code> function that splices the date into the source for us. Consider the following source file:</p><pre><code class="language-julia hljs"># # Example |
|
|
# This example was generated DATEOFTODAY |
|
|
|
|
|
x = 1 // 3</code></pre><p>where <code>DATEOFTODAY</code> is a placeholder, to make it easier for our <code>preprocess</code> function to find the location. Now, lets define the <code>preprocess</code> function, for example</p><pre><code class="language-julia hljs">function update_date(content) |
|
|
content = replace(content, "DATEOFTODAY" => Date(now())) |
|
|
return content |
|
|
end</code></pre><p>which would replace every occurrence of <code>"DATEOFTODAY"</code> with the current date. We would now simply give this function to the generator, for example:</p><pre><code class="language-julia hljs">Literate.markdown("input.jl", "outputdir"; preprocess = update_date)</code></pre><h3 id="Example:-Replacing-include-calls-with-included-code"><a class="docs-heading-anchor" href="#Example:-Replacing-include-calls-with-included-code">Example: Replacing <code>include</code> calls with included code</a><a id="Example:-Replacing-include-calls-with-included-code-1"></a><a class="docs-heading-anchor-permalink" href="#Example:-Replacing-include-calls-with-included-code" title="Permalink"></a></h3><p>Let's say that we have some individual example files <code>file1, file2, ...</code> etc. that are <em>runnable</em> and also following the style of Literate. These files could be for example used in the test suite of your package.</p><p>We want to group them all into a single page in our documentation, but we do not want to copy paste the content of <code>file1, ...</code> for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.</p><p>A very easy way to do this is using <code>preprocess</code> to interchange <code>include</code> statements with file content. First, create a runnable <code>.jl</code> following the format of Literate</p><pre><code class="language-julia hljs"># # Replace includes |
|
|
# This is an example to replace `include` calls with the actual file content. |
|
|
|
|
|
include("file1.jl") |
|
|
|
|
|
# Cool, we just saw the result of the above code snippet. Here is one more: |
|
|
|
|
|
include("file2.jl")</code></pre><p>Let's say we have saved this file as <code>examples.jl</code>. Then, you want to properly define a pre-processing function:</p><pre><code class="language-julia hljs">function replace_includes(str) |
|
|
|
|
|
included = ["file1.jl", "file2.jl"] |
|
|
|
|
|
# Here the path loads the files from their proper directory, |
|
|
# which may not be the directory of the `examples.jl` file! |
|
|
path = "directory/to/example/files/" |
|
|
|
|
|
for ex in included |
|
|
content = read(path*ex, String) |
|
|
str = replace(str, "include(\"$(ex)\")" => content) |
|
|
end |
|
|
return str |
|
|
end</code></pre><p>(of course replace <code>included</code> with your respective files)</p><p>Finally, you simply pass this function to e.g. <a href="../outputformats/#Literate.markdown"><code>Literate.markdown</code></a> as</p><pre><code class="language-julia hljs">Literate.markdown("examples.jl", "path/to/save/markdown"; |
|
|
name = "markdown_file_name", preprocess = replace_includes)</code></pre><p>and you will see that in the final output file (here <code>markdown_file_name.md</code>) the <code>include</code> statements are replaced with the actual code to be included!</p><p>This approach is used for generating <a href="https://juliadynamics.github.io/TimeseriesPrediction.jl/latest/stexamples/">the examples</a> in the documentation of the <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl">TimeseriesPrediction.jl</a> package. The <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl/tree/dcb080376a7861716147c04e45c473f55bb9a078/examples">example files</a>, included together in the <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl/blob/dcb080376a7861716147c04e45c473f55bb9a078/docs/src/stexamples.jl">stexamples.jl</a> file, are processed by literate via this <a href="https://github.com/JuliaDynamics/TimeseriesPrediction.jl/blob/dcb080376a7861716147c04e45c473f55bb9a078/docs/make.jl">make.jl</a> file to generate the markdown and code cells of the documentation.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../outputformats/">« <strong>4.</strong> Output formats</a><a class="docs-footer-nextpage" href="../documenter/"><strong>6.</strong> Interaction with Documenter.jl »</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="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Sunday 1 December 2024 23:38">Sunday 1 December 2024</span>. Using Julia version 1.11.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
|
|
|
|
