Skip to content

Commit

Permalink
Built site for gh-pages
Browse files Browse the repository at this point in the history
  • Loading branch information
@mjfrigaard
mjfrigaard committed Nov 3, 2023
1 parent 71c9621 commit c87b3d5
Show file tree
Hide file tree
Showing 18 changed files with 204 additions and 195 deletions.
2 changes: 1 addition & 1 deletion .nojekyll
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1bc9388a
8f159f3b
2 changes: 1 addition & 1 deletion app_packages.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -567,7 +567,7 @@ <h3 class="anchored" data-anchor-id="development-chapter-4">Development (Chapter
<dl class="code-annotation-container-hidden code-annotation-container-grid">
<dt data-target-cell="annotated-cell-1" data-target-annotation="1">1</dt>
<dd>
<span data-code-annotation="1" data-code-lines="10" data-code-cell="annotated-cell-1">Always leave an empty line in the <code>DESCRIPTION</code></span>
<span data-code-cell="annotated-cell-1" data-code-lines="10" data-code-annotation="1">Always leave an empty line in the <code>DESCRIPTION</code></span>
</dd>
</dl>
</div>
Expand Down
4 changes: 2 additions & 2 deletions comparisons.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -453,7 +453,7 @@ <h3 class="anchored" data-anchor-id="waldo"><span style="font-size: 1.05em;"><co
<dl class="code-annotation-container-hidden code-annotation-container-grid">
<dt data-target-cell="annotated-cell-1" data-target-annotation="1">1</dt>
<dd>
<span data-code-cell="annotated-cell-1" data-code-annotation="1" data-code-lines="2,3">Comparing identical objects</span>
<span data-code-annotation="1" data-code-lines="2,3" data-code-cell="annotated-cell-1">Comparing identical objects</span>
</dd>
</dl>
</div>
Expand Down Expand Up @@ -486,7 +486,7 @@ <h3 class="anchored" data-anchor-id="waldo"><span style="font-size: 1.05em;"><co
<dl class="code-annotation-container-hidden code-annotation-container-grid">
<dt data-target-cell="annotated-cell-2" data-target-annotation="1">1</dt>
<dd>
<span data-code-cell="annotated-cell-2" data-code-annotation="1" data-code-lines="2,3">Comparing different objects</span>
<span data-code-annotation="1" data-code-lines="2,3" data-code-cell="annotated-cell-2">Comparing different objects</span>
</dd>
</dl>
</div>
Expand Down
37 changes: 7 additions & 30 deletions dependencies.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -545,7 +545,7 @@ <h2 class="anchored" data-anchor-id="moviesapp"><span style="font-size: 1.05em">
<dl class="code-annotation-container-hidden code-annotation-container-grid">
<dt data-target-cell="annotated-cell-1" data-target-annotation="1">1</dt>
<dd>
<span data-code-cell="annotated-cell-1" data-code-annotation="1" data-code-lines="13,21">The <code>man</code> folder now contains the help (<code>.Rd</code>) files for the functions in <code>R/</code></span>
<span data-code-annotation="1" data-code-lines="13,21" data-code-cell="annotated-cell-1">The <code>man</code> folder now contains the help (<code>.Rd</code>) files for the functions in <code>R/</code></span>
</dd>
</dl>
</div>
Expand Down Expand Up @@ -925,29 +925,6 @@ <h4 class="anchored" data-anchor-id="the-search-list">The <span style="font-size
</section>
<section id="exporting-scatter_plot" class="level4 page-columns page-full">
<h4 class="anchored" data-anchor-id="exporting-scatter_plot">Exporting <span style="font-size: 1.05em;"><code>scatter_plot()</code></span></h4>
<p>Shiny apps often contain utility functions in <code>helper.R</code> or <code>utils.R</code> files. Storing non-shiny code in these files isn’t a bad practice (in fact, it’s encouraged in <a href="https://mastering-shiny.org/scaling-functions.html#file-organisation">Mastering Shiny</a>). However, if we’re following the advice in <a href="https://r-pkgs.org/dependencies-in-practice.html#what-to-export">R Packages</a>, we should rename <code>R/utils.R</code> as we transition to an app-package,</p>
<blockquote class="blockquote">
<p><em>‘most of our packages have a <code>utils.R</code> file (<a href="https://r-pkgs.org/code.html#sec-code-organising">Section 6.1</a>) that contains small utility functions that are useful internally, but aren’t part of the core purpose of those packages. We don’t export such functions.’</em></p>
</blockquote>
<div class="callout callout-style-default callout-note callout-titled">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-5-contents" aria-controls="callout-5" aria-expanded="true" aria-label="Toggle callout">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
<span style="font-weight: bold; font-size: 1.10em;"><code>R/utils.R</code> &gt;&gt; <code>R/scatter_plot.R</code></span>
</div>
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
</div>
<div id="callout-5" class="callout-5-contents callout-collapse collapse show">
<div class="callout-body-container callout-body">
<div style="font-size: 1.05em; color: #282b2d;">
<p>From now on, I’ve renamed <code>R/utils.R</code> to <code>R/scatter_plot.R</code>, so it aligns with the naming conventions in other R packages.</p>
<p>For a deep dive on <code>R/utils.R</code> files in R packages, I recommend reading <a href="https://rud.is/b/2018/04/08/dissecting-r-package-utility-belts/">Dissecting R Package “Utility Belts”</a></p>
</div>
</div>
</div>
</div>
<p>Let’s add the <code>@export</code> tag to <code>R/scatter_plot.R</code> so it’s exported from <code>moviesApp</code>.</p>
<div class="cell">
<div class="sourceCode cell-code" id="cb23"><pre class="sourceCode r code-with-copy"><code class="sourceCode r"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="co">#' Create scatter plot </span></span>
Expand Down Expand Up @@ -1061,7 +1038,7 @@ <h3 class="anchored" data-anchor-id="what-to-export">What to <span style="font-s
</ul>
<p>You’ll rarely want to export everything, but it might be helpful if the primary audience for your app-package is other developers within your organization. See the <strong>Low-key <code>@export</code>s with <code>@keywords internal</code></strong> box below for exporting functions without including them in your package index.</p>
<div class="callout callout-style-default callout-tip callout-titled">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-6-contents" aria-controls="callout-6" aria-expanded="false" aria-label="Toggle callout">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-5-contents" aria-controls="callout-5" aria-expanded="false" aria-label="Toggle callout">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
Expand All @@ -1070,7 +1047,7 @@ <h3 class="anchored" data-anchor-id="what-to-export">What to <span style="font-s
</div>
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
</div>
<div id="callout-6" class="callout-6-contents callout-collapse collapse">
<div id="callout-5" class="callout-5-contents callout-collapse collapse">
<div class="callout-body-container callout-body">
<div style="font-size: 1.05em; color: #282b2d;">
<p>If you’d like function to be exported, but not listed in the package index, you can combine <code>@export</code> with <code>@keywords internal</code>. These should be used in combination,</p>
Expand Down Expand Up @@ -1186,7 +1163,7 @@ <h3 class="anchored" data-anchor-id="imports-in-moviesapp">Imports in <code>movi
<dl class="code-annotation-container-hidden code-annotation-container-grid">
<dt data-target-cell="annotated-cell-24" data-target-annotation="1">1</dt>
<dd>
<span data-code-cell="annotated-cell-24" data-code-annotation="1" data-code-lines="10">Import entire shiny package namespace</span>
<span data-code-annotation="1" data-code-lines="10" data-code-cell="annotated-cell-24">Import entire shiny package namespace</span>
</dd>
</dl>
</div>
Expand Down Expand Up @@ -1228,7 +1205,7 @@ <h3 class="anchored" data-anchor-id="imports-in-moviesapp">Imports in <code>movi
<dl class="code-annotation-container-hidden code-annotation-container-grid">
<dt data-target-cell="annotated-cell-25" data-target-annotation="1">1</dt>
<dd>
<span data-code-cell="annotated-cell-25" data-code-annotation="1" data-code-lines="26">Import a the <code>.data</code> operator from <code>rlang</code></span>
<span data-code-annotation="1" data-code-lines="26" data-code-cell="annotated-cell-25">Import a the <code>.data</code> operator from <code>rlang</code></span>
</dd>
</dl>
</div>
Expand Down Expand Up @@ -1425,7 +1402,7 @@ <h2 class="anchored" data-anchor-id="checking-dependencies">Checking dependencie
<h2 class="anchored" data-anchor-id="recap">Recap</h2>
<p>Below are the main takeaways from managing the imports and exports from your app-package:</p>
<div class="callout callout-style-default callout-note callout-titled">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-7-contents" aria-controls="callout-7" aria-expanded="true" aria-label="Toggle callout">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-6-contents" aria-controls="callout-6" aria-expanded="true" aria-label="Toggle callout">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
Expand All @@ -1434,7 +1411,7 @@ <h2 class="anchored" data-anchor-id="recap">Recap</h2>
</div>
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
</div>
<div id="callout-7" class="callout-7-contents callout-collapse collapse show">
<div id="callout-6" class="callout-6-contents callout-collapse collapse show">
<div class="callout-body-container callout-body">
<div style="font-size: 1.05em; color: #282b2d;">
<p>This chapter covered:</p>
Expand Down
41 changes: 34 additions & 7 deletions document.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -577,7 +577,7 @@ <h3 class="anchored" data-anchor-id="markdown-true"><span style="font-size: 0.90
<dl class="code-annotation-container-hidden code-annotation-container-grid">
<dt data-target-cell="annotated-cell-3" data-target-annotation="1">1</dt>
<dd>
<span data-code-lines="13" data-code-cell="annotated-cell-3" data-code-annotation="1">Always leave at least one empty final line in your <code>DESCRIPTION</code> file.</span>
<span data-code-cell="annotated-cell-3" data-code-lines="13" data-code-annotation="1">Always leave at least one empty final line in your <code>DESCRIPTION</code> file.</span>
</dd>
</dl>
</div>
Expand Down Expand Up @@ -669,6 +669,26 @@ <h6 class="anchored" data-anchor-id="section"></h6>
<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a>ℹ Loading moviesApp</span>
<span id="cb11-3"><a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>Writing scatter_plot.Rd</span>
<span id="cb11-4"><a href="#cb11-4" aria-hidden="true" tabindex="-1"></a>Documentation completed</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<p>Shiny apps often contain utility functions in <code>helper.R</code> or <code>utils.R</code> files. Storing non-shiny code in these files isn’t a bad practice (in fact, it’s encouraged in <a href="https://mastering-shiny.org/scaling-functions.html#file-organisation">Mastering Shiny</a>). However, if we’re following the advice in <a href="https://r-pkgs.org/dependencies-in-practice.html#what-to-export">R Packages</a>,<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> we should rename <code>R/utils.R</code> to <code>R/scatter_plot.R</code> so it matches <code>man/scatter_plot.Rd</code> as we transition to an app-package.<a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a></p>
<div class="callout callout-style-default callout-note callout-titled">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-5-contents" aria-controls="callout-5" aria-expanded="true" aria-label="Toggle callout">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
<div class="callout-title-container flex-fill">
<span style="font-weight: bold; font-size: 1.10em;"><code>R/utils.R</code> &gt;&gt; <code>R/scatter_plot.R</code></span>
</div>
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
</div>
<div id="callout-5" class="callout-5-contents callout-collapse collapse show">
<div class="callout-body-container callout-body">
<div style="font-size: 1.05em; color: #282b2d;">
<p>From now on, I’ve renamed <code>R/utils.R</code> to <code>R/scatter_plot.R</code>, so it aligns with the naming conventions in other R packages.</p>
<p>For a deep dive on <code>R/utils.R</code> files in R packages, I recommend reading <a href="https://rud.is/b/2018/04/08/dissecting-r-package-utility-belts/">Dissecting R Package “Utility Belts”</a></p>
</div>
</div>
</div>
</div>
<p>R documentation (<code>.Rd</code>) files have a formatting style similar to <a href="https://www.latex-project.org/">(La)TeX</a> (but <code>roxygen2</code> saves us from having to learn this syntax). When we open <code>man/scatter_plot.Rd</code>, we see it contains the following:</p>
<div class="column-body-outset-right">
<div id="fig-doc_scatter_plot_rd" class="quarto-figure quarto-figure-center anchored">
Expand All @@ -684,7 +704,7 @@ <h6 class="anchored" data-anchor-id="section"></h6>
</div>
</div>
<div class="callout callout-style-default callout-note callout-titled">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-5-contents" aria-controls="callout-5" aria-expanded="false" aria-label="Toggle callout">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-6-contents" aria-controls="callout-6" aria-expanded="false" aria-label="Toggle callout">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
Expand All @@ -693,7 +713,7 @@ <h6 class="anchored" data-anchor-id="section"></h6>
</div>
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
</div>
<div id="callout-5" class="callout-5-contents callout-collapse collapse">
<div id="callout-6" class="callout-6-contents callout-collapse collapse">
<div class="callout-body-container callout-body">
<div style="font-size: 1.05em; color: #282b2d;">
<p><code>roxygen2</code> graciously generates the <code>scatter_plot.Rd</code> file (and warns us not to edit it by hand).</p>
Expand Down Expand Up @@ -781,7 +801,7 @@ <h3 class="anchored" data-anchor-id="examples"><span style="font-size: 0.90em;">
<span id="cb14-6"><a href="#cb14-6" aria-hidden="true" tabindex="-1"></a>#' alpha_var = 0.5, </span>
<span id="cb14-7"><a href="#cb14-7" aria-hidden="true" tabindex="-1"></a>#' size_var = 3)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
<div class="callout callout-style-default callout-tip callout-titled">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-6-contents" aria-controls="callout-6" aria-expanded="false" aria-label="Toggle callout">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-7-contents" aria-controls="callout-7" aria-expanded="false" aria-label="Toggle callout">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
Expand All @@ -790,7 +810,7 @@ <h3 class="anchored" data-anchor-id="examples"><span style="font-size: 0.90em;">
</div>
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
</div>
<div id="callout-6" class="callout-6-contents callout-collapse collapse">
<div id="callout-7" class="callout-7-contents callout-collapse collapse">
<div class="callout-body-container callout-body">
<div style="font-size: 1.05em; color: #282b2d;">
<p>If you’re documenting your package functions in Posit Workbench, tab-completion is your friend! The help text displayed with each tag ensures you’re including the correct version (see <code>@example</code> vs.&nbsp;<code>@examples</code> below).</p>
Expand Down Expand Up @@ -1473,7 +1493,7 @@ <h2 class="anchored" data-anchor-id="recap">Recap</h2>
<p>Good documentation aims to make it as easy as possible for others (and future you) to understand what your function does and how to use it.</p>
<p>Below is a recap of the topics covered in this chapter.</p>
<div class="callout callout-style-default callout-note callout-titled">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-7-contents" aria-controls="callout-7" aria-expanded="true" aria-label="Toggle callout">
<div class="callout-header d-flex align-content-center" data-bs-toggle="collapse" data-bs-target=".callout-8-contents" aria-controls="callout-8" aria-expanded="true" aria-label="Toggle callout">
<div class="callout-icon-container">
<i class="callout-icon"></i>
</div>
Expand All @@ -1482,7 +1502,7 @@ <h2 class="anchored" data-anchor-id="recap">Recap</h2>
</div>
<div class="callout-btn-toggle d-inline-block border-0 py-1 ps-1 pe-0 float-end"><i class="callout-toggle"></i></div>
</div>
<div id="callout-7" class="callout-7-contents callout-collapse collapse show">
<div id="callout-8" class="callout-8-contents callout-collapse collapse show">
<div class="callout-body-container callout-body">
<div style="font-size: 1.05em; color: #282b2d;">
<p>This chapter covered:</p>
Expand All @@ -1504,6 +1524,13 @@ <h2 class="anchored" data-anchor-id="recap">Recap</h2>
<p>In the next section, we’ll use <code>roxygen2</code> to manage our app-package dependencies.</p>


</section>
<section id="footnotes" class="footnotes footnotes-end-of-document" role="doc-endnotes">
<hr>
<ol>
<li id="fn1"><p><em>‘most of our packages have a <code>utils.R</code> file (<a href="https://r-pkgs.org/code.html#sec-code-organising">Section 6.1</a>) that contains small utility functions that are useful internally, but aren’t part of the core purpose of those packages. We don’t export such functions.’</em><a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn2"><p>Having a 1:1 match on function and file names will also make writing and running tests easier.<a href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
</ol>
</section>

</main> <!-- /main -->
Expand Down
Loading

0 comments on commit c87b3d5

Please sign in to comment.