Skip to content

Commit

Permalink
build based on 1133de2
Browse files Browse the repository at this point in the history
  • Loading branch information
Documenter.jl committed Jul 11, 2024
1 parent 975d22c commit a709ced
Show file tree
Hide file tree
Showing 10 changed files with 11 additions and 11 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><li><a class="tocitem" href="../custom_settings/">Custom Settings</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 an AbstractString (or a <code>@raw_str</code>) 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="Sunday 30 June 2024 17:30">Sunday 30 June 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="Thursday 11 July 2024 23:28">Thursday 11 July 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
2 changes: 1 addition & 1 deletion dev/frompackage/custom_settings/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@
setting2 = val2
end
import *
end</code></pre><p>Only assignments are supported inside the <code>@settings</code> block and only primitive values can be used as <code>val</code>, i.e. anything that is parsed as an <code>Expr</code> as macro argument is not a valid <code>val</code>.</p><p>These are the supported settings:</p><h2 id="SHOULD_PREPEND_LOAD_PATH"><a class="docs-heading-anchor" href="#SHOULD_PREPEND_LOAD_PATH"><code>SHOULD_PREPEND_LOAD_PATH</code></a><a id="SHOULD_PREPEND_LOAD_PATH-1"></a><a class="docs-heading-anchor-permalink" href="#SHOULD_PREPEND_LOAD_PATH" title="Permalink"></a></h2><p><code>Bool</code> value that <strong>defaults to <code>false</code></strong>. </p><p>This specifies whether the active environment added to the <code>LOAD_PATH</code> by the macro should go to the end or to the front of the <code>LOAD_PATH</code>. In some cases it can be useful to have the custom environment at the beginning of the LOAD_PATH for the purpose of locating packages.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../package_extensions/">« Package Extensions</a><a class="docs-footer-nextpage" href="../../other_functions/">Other Exports »</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="Sunday 30 June 2024 17:30">Sunday 30 June 2024</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
end</code></pre><p>Only assignments are supported inside the <code>@settings</code> block and only primitive values can be used as <code>val</code>, i.e. anything that is parsed as an <code>Expr</code> as macro argument is not a valid <code>val</code>.</p><p>These are the supported settings:</p><h2 id="SHOULD_PREPEND_LOAD_PATH"><a class="docs-heading-anchor" href="#SHOULD_PREPEND_LOAD_PATH"><code>SHOULD_PREPEND_LOAD_PATH</code></a><a id="SHOULD_PREPEND_LOAD_PATH-1"></a><a class="docs-heading-anchor-permalink" href="#SHOULD_PREPEND_LOAD_PATH" title="Permalink"></a></h2><p><code>Bool</code> value that <strong>defaults to <code>false</code></strong>. </p><p>This specifies whether the active environment added to the <code>LOAD_PATH</code> by the macro should go to the end or to the front of the <code>LOAD_PATH</code>. In some cases it can be useful to have the custom environment at the beginning of the LOAD_PATH for the purpose of locating packages.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../package_extensions/">« Package Extensions</a><a class="docs-footer-nextpage" href="../../other_functions/">Other Exports »</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="Thursday 11 July 2024 23:28">Thursday 11 July 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 a709ced

Please sign in to comment.