Skip to content

Commit

Permalink
build based on 3cf3019
Browse files Browse the repository at this point in the history
  • Loading branch information
Documenter.jl committed Feb 16, 2024
1 parent b6498d8 commit 229f5d5
Show file tree
Hide file tree
Showing 10 changed files with 10 additions and 10 deletions.
2 changes: 1 addition & 1 deletion dev/frompackage/basic_use/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Basic Use · PlutoDevMacros.jl</title><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.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></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../../">PlutoDevMacros.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="../../">Home</a></li><li><span class="tocitem">@frompackage/@fromparent</span><ul><li><a class="tocitem" href="../introduction/">Introduction</a></li><li class="is-active"><a class="tocitem" href>Basic Use</a><ul class="internal"><li><a class="tocitem" href="#target-path"><span><code>target</code> path</span></a></li><li><a class="tocitem" href="#import_block"><span><code>import_block</code></span></a></li><li><a class="tocitem" href="#Reload-Button"><span>Reload Button</span></a></li></ul></li><li><a class="tocitem" href="../import_statements/">Supported import statements</a></li><li><a class="tocitem" href="../skipping_parts/">Skipping Package Parts</a></li><li><a class="tocitem" href="../use_with_plutopkg/">Use with PlutoPkg</a></li><li><a class="tocitem" href="../package_extensions/">Package Extensions</a></li></ul></li><li><a class="tocitem" href="../../other_functions/">Other Exports</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><a class="is-disabled">@frompackage/@fromparent</a></li><li class="is-active"><a href>Basic Use</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Basic Use</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/disberd/PlutoDevMacros.jl/blob/master/docs/src/frompackage/basic_use.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="Basic-Use"><a class="docs-heading-anchor" href="#Basic-Use">Basic Use</a><a id="Basic-Use-1"></a><a class="docs-heading-anchor-permalink" href="#Basic-Use" title="Permalink"></a></h1><pre><code class="language-julia hljs">@fromparent import_block
@frompackage target import_block</code></pre><p>The <code>@frompackage</code> macro takes a local Package (derived from the <code>target</code> path), loads it as a submodule of the current Pluto workspace and then process the various import/using statements inside <code>import_block</code> to extract varables/functions from the local Package into the notebook workspace.</p><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p><code>@fromparent</code> is simply a convenience synthax that uses the calling notebook file as <code>target</code>. More details on how the target path is processed are given below.<br/><br/>Due to the equivalence in functionality between <code>@frompackage</code> and <code>@fromparent</code>, the rest of the documentation will only refer to <code>@frompackage</code> for convenience.</p></div></div><p>When changes to the code of the local Package are made, the cell containing the call to <code>@frompackage</code> can be re-executed to reload the most recent version of the module. Thanks to Pluto&#39;s reactivity, this will automatically trigger re-execution of all cells that use functionality defined in the local package loaded by the macro.</p><p>When testing functionalities of the local package using statements in the notebook cells, this reactivity simplifies the workflow as one does not need to manually re-run tests. At the same time, re-loading the full package module at each statement (similar to what Revise does) would most likely generate a significant overhead.</p><p>For this reason the <em>reload</em> of local code is only triggered manually within <code>@frompackage</code> and happens only when manually re-running the cell containing the macro call. This process is simplified by the reload button explained <a href="#Reload-Button">below</a>.</p><h2 id="target-path"><a class="docs-heading-anchor" href="#target-path"><code>target</code> path</a><a id="target-path-1"></a><a class="docs-heading-anchor-permalink" href="#target-path" title="Permalink"></a></h2><p>The first argument to <code>@frompackage</code> (<code>target</code>) has to be a String containing the path (either absolute or relative to the file calling the macro) that points to a local Package (the path can be to any file or subfolder within the Package folder).</p><p>The main module of the package identified by the <code>target</code> path will be used as the module to process and load within the calling notebook</p><h2 id="import_block"><a class="docs-heading-anchor" href="#import_block"><code>import_block</code></a><a id="import_block-1"></a><a class="docs-heading-anchor-permalink" href="#import_block" title="Permalink"></a></h2><p>The second argument to the macro is supposed to be either a single <code>using</code>/<code>import</code> statement, or multiple statements wrapped inside a <code>begin...end</code> block.</p><p>These statements are used to select which parts of the loaded Package module have to be evaluated and which of its variables have te be imported within the notebook scope. Most of these import statements are only relevant when called within Pluto, so <code>@frompackage</code> simply avoid loading the target Package and deletes these import statements <strong>in most cases</strong> when called oustide of Pluto. There is a specific type of import statement (relative import) that is relevant and applicable also outside of Pluto, so this kind of statement is maintained in the macro output even outside of Pluto.</p><p>The macro respects the differentiation between <code>using</code> and <code>import</code> as in normal Julia, so statements containing <code>using Module</code> without any variable name specifier will import all the exported names of <code>Module</code>.</p><h2 id="Reload-Button"><a class="docs-heading-anchor" href="#Reload-Button">Reload Button</a><a id="Reload-Button-1"></a><a class="docs-heading-anchor-permalink" href="#Reload-Button" title="Permalink"></a></h2><p>When called within Pluto, the <code>@frompackage</code> macro also creates a convenient button that can be used to re-execute the cell calling the macro to reload the Package code due to a change in the source files.</p><p>This button can also be used to quickly navigate to the position of the cell containing the macro by using <strong>Ctrl+Click</strong>.<br/>The reload button will change appearance (getting a red border) when the macrocall incur in a runtime error either due to incorrect import statement (like if a relative import is used without a proper target) or due to an error encountered when loading the package code.</p><p>Here is a short video showing the reload button. The window on the left has opened the <a href="https://github.com/disberd/PlutoDevMacros.jl/blob/8e481f552fdce1562cc9e45970cb11e8b54faa71/test/TestPackage/src/specific_imports1.jl">specific_imports1.jl</a> notebook, while the one on the right has the <a href="https://github.com/disberd/PlutoDevMacros.jl/blob/8e481f552fdce1562cc9e45970cb11e8b54faa71/test/TestPackage/src/specific_imports2.jl">specific_imports2.jl</a> one. </p><p>Both are included in the TestPackage using for tests and defined in <a href="https://github.com/disberd/PlutoDevMacros.jl/blob/f7b2bbf3a89ca677ab1765a2d4fcb3a1600d66f6/test/TestPackage/src/TestPackage.jl">test/TestPackage/src/TestPackage.jl</a></p><video controls=true>
<source src="https://user-images.githubusercontent.com/12846528/236453634-c95aa7b2-61eb-492f-85f5-6539bbb714d5.mp4" type="video/mp4">
</video></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../introduction/">« Introduction</a><a class="docs-footer-nextpage" href="../import_statements/">Supported import statements »</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.25 on <span class="colophon-date" title="Monday 8 January 2024 14:56">Monday 8 January 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
</video></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../introduction/">« Introduction</a><a class="docs-footer-nextpage" href="../import_statements/">Supported import statements »</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.25 on <span class="colophon-date" title="Friday 16 February 2024 11:01">Friday 16 February 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
Loading

0 comments on commit 229f5d5

Please sign in to comment.