rdev/docs/reference/build_analysis_site.html at 067da8ad3c393f0c941081c54f046a61fa46c113 · jabenninghoff/rdev · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en-US"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><title>Build Analysis Site — build_analysis_site • rdev</title><!-- favicons --><link rel="icon" type="image/png" sizes="96x96" href="../favicon-96x96.png"><link rel="icon" type="”image/svg+xml”" href="../favicon.svg"><link rel="apple-touch-icon" sizes="180x180" href="../apple-touch-icon.png"><link rel="icon" sizes="any" href="../favicon.ico"><link rel="manifest" href="../site.webmanifest"><script src="../lightswitch.js"></script><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../deps/font-awesome-6.5.2/css/all.min.css" rel="stylesheet"><link href="../deps/font-awesome-6.5.2/css/v4-shims.min.css" rel="stylesheet"><script src="../deps/headroom-0.11.0/headroom.min.js"></script><script src="../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../deps/search-1.0.0/fuse.min.js"></script><script src="../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../pkgdown.js"></script><link href="../extra.css" rel="stylesheet"><meta property="og:title" content="Build Analysis Site — build_analysis_site"><meta name="description" content="build_analysis_site() is a wrapper for pkgdown::build_site_github_pages() that adds an
'Analysis' menu containing rendered versions of all .Rmd files in analysis/."><meta property="og:description" content="build_analysis_site() is a wrapper for pkgdown::build_site_github_pages() that adds an
'Analysis' menu containing rendered versions of all .Rmd files in analysis/."><meta property="og:image" content="https://jabenninghoff.github.io/rdev/logo.png"></head><body>
    <a href="#main" class="visually-hidden-focusable">Skip to contents</a>


    <nav class="navbar navbar-expand-lg fixed-top " aria-label="Site navigation"><div class="container">

    <a class="navbar-brand me-2" href="../index.html">rdev</a>

    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.15.5</small>


    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>

    <div id="navbar" class="collapse navbar-collapse ms-3">
      <ul class="navbar-nav me-auto"><li class="nav-item"><a class="nav-link" href="../articles/rdev.html">Get started</a></li>
<li class="active nav-item"><a class="nav-link" href="../reference/index.html">Reference</a></li>
<li class="nav-item dropdown">
  <button class="nav-link dropdown-toggle" type="button" id="dropdown-articles" data-bs-toggle="dropdown" aria-expanded="false" aria-haspopup="true">Articles</button>
  <ul class="dropdown-menu" aria-labelledby="dropdown-articles"><li><a class="dropdown-item" href="../articles/analysis-package-layout.html">Analysis Package Layout</a></li>
    <li><a class="dropdown-item" href="../articles/style-guide.html">Style Guide</a></li>
  </ul></li>
<li class="nav-item"><a class="nav-link" href="../news/index.html">Changelog</a></li>
      </ul><ul class="navbar-nav"><li class="nav-item"><form class="form-inline" role="search">
 <input class="form-control" type="search" name="search-input" id="search-input" autocomplete="off" aria-label="Search site" placeholder="Search for" data-search-index="../search.json"></form></li>
<li class="nav-item"><a class="external-link nav-link" href="https://github.com/jabenninghoff/rdev/" aria-label="GitHub"><span class="fa fab fa-github fa-lg"></span></a></li>
<li class="nav-item dropdown">
  <button class="nav-link dropdown-toggle" type="button" id="dropdown-lightswitch" data-bs-toggle="dropdown" aria-expanded="false" aria-haspopup="true" aria-label="Light switch"><span class="fa fa-sun"></span></button>
  <ul class="dropdown-menu dropdown-menu-end" aria-labelledby="dropdown-lightswitch"><li><button class="dropdown-item" data-bs-theme-value="light"><span class="fa fa-sun"></span> Light</button></li>
    <li><button class="dropdown-item" data-bs-theme-value="dark"><span class="fa fa-moon"></span> Dark</button></li>
    <li><button class="dropdown-item" data-bs-theme-value="auto"><span class="fa fa-adjust"></span> Auto</button></li>
  </ul></li>
      </ul></div>


  </div>
</nav><div class="container template-reference-topic">
<div class="row">
  <main id="main" class="col-md-9"><div class="page-header">
      <img src="../logo.png" class="logo" alt=""><h1>Build Analysis Site</h1>
      <small class="dont-index">Source: <a href="https://github.com/jabenninghoff/rdev/blob/HEAD/R/build.R" class="external-link"><code>R/build.R</code></a></small>
      <div class="d-none name"><code>build_analysis_site.Rd</code></div>
    </div>

    <div class="ref-description section level2">
    <p><code>build_analysis_site()</code> is a wrapper for <code><a href="https://pkgdown.r-lib.org/reference/build_site_github_pages.html" class="external-link">pkgdown::build_site_github_pages()</a></code> that adds an
'Analysis' menu containing rendered versions of all .Rmd files in <code>analysis/</code>.</p>
    </div>

    <div class="section level2">
    <h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">build_analysis_site</span><span class="op">(</span>pkg <span class="op">=</span> <span class="st">"."</span>, <span class="va">...</span><span class="op">)</span></span></code></pre></div>
    </div>

    <div class="section level2">
    <h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>


<dl><dt id="arg-pkg">pkg<a class="anchor" aria-label="anchor" href="#arg-pkg"></a></dt>
<dd><p>Path to package. Currently, only <code>pkg = "."</code> is supported.</p></dd>


<dt id="arg--">...<a class="anchor" aria-label="anchor" href="#arg--"></a></dt>
<dd><p>additional arguments passed to <code><a href="https://pkgdown.r-lib.org/reference/build_site_github_pages.html" class="external-link">pkgdown::build_site_github_pages()</a></code> (not implemented)</p></dd>

</dl></div>
    <div class="section level2">
    <h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>
    <p>rmarkdown _site.yml as yaml, invisibly</p>
    </div>
    <div class="section level2">
    <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
    <p>When run, <code>build_analysis_site()</code>:</p><ol><li><p>Reads base <a href="https://pkgdown.r-lib.org/reference/pkgdown-package.html" class="external-link">pkgdown::pkgdown</a> settings from <code>pkgdown/_base.yml</code></p></li>
<li><p>Writes base settings to <code>_pkgdown.yml</code></p></li>
<li><p>Creates a template using <code><a href="https://pkgdown.r-lib.org/reference/templates.html" class="external-link">pkgdown::template_navbar()</a></code> and inserts an <code>analysis</code> menu with
links to html versions of each .Rmd file in <code>analysis/</code></p></li>
<li><p>Writes the template to <code>_pkgdown.yml</code></p></li>
<li><p>Updates <code>README.md</code> by running <code><a href="https://devtools.r-lib.org/reference/build_rmd.html" class="external-link">devtools::build_readme()</a></code> (if <code>README.Rmd</code> exists) to update
the list of notebooks</p></li>
<li><p>Runs <code><a href="https://pkgdown.r-lib.org/reference/build_site_github_pages.html" class="external-link">pkgdown::build_site_github_pages()</a></code> with <code>install = TRUE</code> and <code>new_process = TRUE</code></p></li>
<li><p>Creates a <code>_site.yml</code> file based on the final <code>_pkgdown.yml</code> that clones the <a href="https://pkgdown.r-lib.org/reference/pkgdown-package.html" class="external-link">pkgdown::pkgdown</a> navbar
in a temporary build directory</p></li>
<li><p>Copies the following from <code>analysis/</code> into the build directory: <code>*.Rmd</code>, <code>assets/</code>, <code>data/</code>,
<code>import/</code>, <code>rendered/</code></p></li>
<li><p>Changes <code>*.Rmd</code> from <code>html_notebook</code> to <code>html_document</code> using <code><a href="to_document.html">to_document()</a></code></p></li>
<li><p>Builds a site using <code><a href="https://pkgs.rstudio.com/rmarkdown/reference/render_site.html" class="external-link">rmarkdown::render_site()</a></code> using modified <code>html_document</code> output settings
to render files with the look and feel of <code>html_notebook</code></p></li>
<li><p>Moves the rendered files to <code>docs/</code>: <code>*.html</code>, <code>assets/</code>, <code>rendered/</code>, without overwriting</p></li>
</ol><p><code>build_analysis_site()</code> will fail with an error if there are no files in <code>analysis/*.Rmd</code>, or if
<code>pkgdown/_base.yml</code> does not exist.</p>
    </div>
    <div class="section level2">
    <h2 id="continuous-integration">Continuous Integration<a class="anchor" aria-label="anchor" href="#continuous-integration"></a></h2>


<p>Both <code><a href="build_rdev_site.html">build_rdev_site()</a></code> and <code>build_analysis_site()</code> are meant to be used as part of a CI/CD
workflow, and temporarily set the environment variable <code>CI == "TRUE"</code> so that the build will
fail when non-internal topics are not included on the reference index page per
<code><a href="https://pkgdown.r-lib.org/reference/build_reference.html" class="external-link">pkgdown::build_reference()</a></code>.</p>
    </div>
    <div class="section level2">
    <h2 id="supported-file-types">Supported File Types<a class="anchor" aria-label="anchor" href="#supported-file-types"></a></h2>


<p>While <code><a href="build_quarto_site.html">build_quarto_site()</a></code> supports both R Markdown (<code>.Rmd</code>) and Quarto (<code>.qmd</code>) notebooks in
the <code>analysis</code> directory interchangeably, <code>build_analysis_site()</code> supports <code>.Rmd</code> files only.</p>
    </div>

  </main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
    </nav></aside></div>


    <footer><div class="pkgdown-footer-left">
  <p>Developed by John Benninghoff.</p>
</div>

<div class="pkgdown-footer-right">
  <p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.2.0.</p>
</div>

    </footer></div>


  </body></html>