- validate plugin against the template</code></pre><p>The plugin validation step uses the <ahref="#PkgTemplates.validate"><code>validate</code></a> function. It lets us catch mistakes before we try to generate packages.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.validate"href="#PkgTemplates.validate"><code>PkgTemplates.validate</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">validate(::Plugin, ::Template)</code></pre><p>Perform any required validation for a <ahref="#PkgTemplates.Plugin"><code>Plugin</code></a>.</p><p>It is preferred to do validation here instead of in <ahref="#PkgTemplates.prehook"><code>prehook</code></a>, because this function is called at <ahref="../user/#PkgTemplates.Template"><code>Template</code></a> construction time, whereas the prehook is only run at package generation time.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL145-L153">source</a></section></article><p>The package generation process looks like this:</p><pre><codeclass="language-none">- create empty directory for the package
- run plugin posthook</code></pre><p>As you can tell, plugins play a central role in setting up a package.</p><p>The three main entrypoints for plugins to do work are the <ahref="#PkgTemplates.prehook"><code>prehook</code></a>, the <ahref="#PkgTemplates.hook"><code>hook</code></a>, and the <ahref="#PkgTemplates.posthook"><code>posthook</code></a>. As the names might imply, they basically mean "before the main stage", "the main stage", and "after the main stage", respectively.</p><p>Each stage is basically identical, since the functions take the exact same arguments. However, the multiple stages allow us to depend on artifacts of the previous stages. For example, the <ahref="../user/#PkgTemplates.Git"><code>Git</code></a> plugin uses <ahref="#PkgTemplates.posthook"><code>posthook</code></a> to commit all generated files, but it wouldn't make sense to do that before the files are generated.</p><p>But what about dependencies within the same stage? In this case, we have <ahref="#PkgTemplates.priority"><code>priority</code></a> to define which plugins go when. The <ahref="../user/#PkgTemplates.Git"><code>Git</code></a> plugin also uses this function to lower its posthook's priority, so that even if other plugins generate files in their posthooks, they still get committed (provided that those plugins didn't set an even lower priority).</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.prehook"href="#PkgTemplates.prehook"><code>PkgTemplates.prehook</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">prehook(::Plugin, ::Template, pkg_dir::AbstractString)</code></pre><p>Stage 1 of the package generation process (the "before" stage, in general). At this point, <code>pkg_dir</code> is an empty directory that will eventually contain the package, and neither the <ahref="#PkgTemplates.hook"><code>hook</code></a>s nor the <ahref="#PkgTemplates.posthook"><code>posthook</code></a>s have run.</p><divclass="admonition is-info"><headerclass="admonition-header">Note</header><divclass="admonition-body"><p><code>pkg_dir</code> only stays empty until the first plugin chooses to create a file. See also: <ahref="#PkgTemplates.priority"><code>priority</code></a>.</p></div></div></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL156-L166">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.hook"href="#PkgTemplates.hook"><code>PkgTemplates.hook</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">hook(::Plugin, ::Template, pkg_dir::AbstractString)</code></pre><p>Stage 2 of the package generation pipeline (the "main" stage, in general). At this point, the <ahref="#PkgTemplates.prehook"><code>prehook</code></a>s have run, but not the <ahref="#PkgTemplates.posthook"><code>posthook</code></a>s.</p><p><code>pkg_dir</code> is the directory in which the package is being generated (so <code>basename(pkg_dir)</code> is the package name).</p><divclass="admonition is-info"><headerclass="admonition-header">Note</header><divclass="admonition-body"><p>You usually shouldn't implement this function for <ahref="#PkgTemplates.BasicPlugin"><code>BasicPlugin</code></a>s. If you do, it should probably <code>invoke</code> the generic method (otherwise, there's not much reason to subtype <code>BasicPlugin</code>).</p></div></div></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL169-L182">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.posthook"href="#PkgTemplates.posthook"><code>PkgTemplates.posthook</code></a> — <spanclass="docstring-category">Function</span></header><sectio
end</code></pre><p>The <code>@with_kw_noshow</code> macro defines keyword constructors for us. Inside of our struct definition, we're using <ahref="#PkgTemplates.default_file"><code>default_file</code></a> to refer to files in this repository.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.default_file"href="#PkgTemplates.default_file"><code>PkgTemplates.default_file</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">default_file(paths::AbstractString...) -> String</code></pre><p>Return a path relative to the default template file directory (<code>~/build/invenia/PkgTemplates.jl/templates</code>).</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL9-L14">source</a></section></article><p>The first method we implement for <code>Documenter</code> is <ahref="#PkgTemplates.gitignore"><code>gitignore</code></a>, so that packages created with this plugin ignore documentation build artifacts.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.gitignore"href="#PkgTemplates.gitignore"><code>PkgTemplates.gitignore</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">gitignore(::Plugin) -> Vector{String}</code></pre><p>Return patterns that should be added to <code>.gitignore</code>. These are used by the <ahref="../user/#PkgTemplates.Git"><code>Git</code></a> plugin.</p><p>By default, an empty list is returned.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL80-L87">source</a></section></article><p>Second, we implement <ahref="#PkgTemplates.badges"><code>badges</code></a> to add a couple of badges to new packages' README files.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.badges"href="#PkgTemplates.badges"><code>PkgTemplates.badges</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">badges(::Plugin) -> Union{Badge, Vector{Badge}}</code></pre><p>Return a list of <ahref="#PkgTemplates.Badge"><code>Badge</code></a>s, or just one, to be added to <code>README.md</code>. These are used by the <ahref="../user/#PkgTemplates.Readme"><code>Readme</code></a> plugin to add badges to the README.</p><p>By default, an empty list is returned.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL90-L97">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Badge"href="#PkgTemplates.Badge"><code>PkgTemplates.Badge</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Badge(hover::AbstractString, image::AbstractString, link::AbstractString)</code></pre><p>Container for Markdown badge data. Each argument can contain placeholders, which will be filled in with values from <ahref="#PkgTemplates.combined_view"><code>combined_view</code></a>.</p><p><strong>Arguments</strong></p><ul><li><code>hover::AbstractString</code>: Text to appear when the mouse is hovered over the badge.</li><li><code>image::AbstractString</code>: URL to the image to display.</li><li><code>link::AbstractString</code>: URL to go to upon clicking the badge.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL118-L129">source</a></section></article><p>These two functions, <ahref="#PkgTemplates.gitignore"><code>gitignore</code></a> and <ahref="#PkgTemplates.badges"><code>badges</code></a>, are currently the only "special" functions for cross-plugin interactions. In other cases, y
end</code></pre><p>Validation and all three hooks are implemented:</p><ul><li><ahref="#PkgTemplates.validate"><code>validate</code></a> makes sure that all required Git configuration is present.</li><li><ahref="#PkgTemplates.prehook"><code>prehook</code></a> creates the Git repository for the package.</li><li><ahref="#PkgTemplates.hook"><code>hook</code></a> generates the <code>.gitignore</code> file, using the special <ahref="#PkgTemplates.gitignore"><code>gitignore</code></a> function.</li><li><ahref="#PkgTemplates.posthook"><code>posthook</code></a> adds and commits all the generated files.</li></ul><p>As previously mentioned, we use <ahref="#PkgTemplates.priority"><code>priority</code></a> to make sure that we wait until all other plugins are finished their work before committing files.</p><p>Hopefully, this demonstrates the level of control you have over the package generation process when developing plugins, and when it makes sense to exercise that power!</p><h2id="BasicPlugin-Walkthrough-1"><aclass="docs-heading-anchor"href="#BasicPlugin-Walkthrough-1"><code>BasicPlugin</code> Walkthrough</a><aclass="docs-heading-anchor-permalink"href="#BasicPlugin-Walkthrough-1"title="Permalink"></a></h2><p>Most of the time, you don't really need all of the control that we showed off above. Plugins that subtype <ahref="#PkgTemplates.BasicPlugin"><code>BasicPlugin</code></a> perform a much more limited task. In general, they just generate one templated file.</p><p>To illustrate, let's look at the <ahref="../user/#PkgTemplates.Citation"><code>Citation</code></a> plugin, which creates a <code>CITATION.bib</code> file.</p><pre><codeclass="language-julia">@with_kw_noshow struct Citation <: BasicPlugin
)</code></pre><p>Similar to the <code>Documenter</code> example above, we're defining a keyword constructor, and assigning a default template file from this repository. This plugin adds nothing to <code>.gitignore</code>, and it doesn't add any badges, so implementations for <ahref="#PkgTemplates.gitignore"><code>gitignore</code></a> and <ahref="#PkgTemplates.badges"><code>badges</code></a> are omitted.</p><p>First, we implement <ahref="#PkgTemplates.source"><code>source</code></a> and <ahref="#PkgTemplates.destination"><code>destination</code></a> to define where the template file comes from, and where it goes. These functions are specific to <ahref="#PkgTemplates.BasicPlugin"><code>BasicPlugin</code></a>s, and have no effect on regular <ahref="#PkgTemplates.Plugin"><code>Plugin</code></a>s by default.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.source"href="#PkgTemplates.source"><code>PkgTemplates.source</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">source(::BasicPlugin) -> Union{String, Nothing}</code></pre><p>Return the path to a plugin's template file, or <code>nothing</code> to indicate no file.</p><p>By default, <code>nothing</code> is returned.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL100-L106">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.destination"href="#PkgTemplates.destination"><code>PkgTemplates.destination</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">destination(::BasicPlugin) -> String</code></pre><p>Return the destination, relative to the package root, of a plugin's configuration file.</p><p>This function <strong>must</strong> be implemented.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL109-L115">source</a></section></article><p>Next, we implement <ahref="#PkgTemplates.tags"><code>tags</code></a>. We briefly saw this function earlier, but in this case it's necessary to change its behaviour from the default. To see why, it might help to see the template file in its entirety:</p><pre><codeclass="language-none">@misc{<<&PKG>>.jl,
}</code></pre><p>Because the file contains its own <code>{}</code> delimiters, we need to use different ones for templating to work properly.</p><p>Finally, we implement <ahref="#PkgTemplates.view"><code>view</code></a> to fill in the placeholders that we saw in the template file.</p><h2id="Doing-Extra-Work-With-BasicPlugins-1"><aclass="docs-heading-anchor"href="#Doing-Extra-Work-With-BasicPlugins-1">Doing Extra Work With <code>BasicPlugin</code>s</a><aclass="docs-heading-anchor-permalink"href="#Doing-Extra-Work-With-BasicPlugins-1"title="Permalink"></a></h2><p>Notice that we didn't have to implement <ahref="#PkgTemplates.hook"><code>hook</code></a> for our plugin. It's implemented for all <ahref="#PkgTemplates.BasicPlugin"><code>BasicPlugin</code></a>s, like so:</p><pre><codeclass="language-julia">function render_plugin(p::BasicPlugin, t::Template, pkg::AbstractString)
function hook(p::BasicPlugin, t::Template, pkg_dir::AbstractString)
source(p) === nothing && return
pkg = basename(pkg_dir)
path = joinpath(pkg_dir, destination(p))
text = render_plugin(p, t, pkg)
gen_file(path, text)
end</code></pre><p>But what if we want to do a little more than just generate one file?</p><p>A good example of this is the <ahref="../user/#PkgTemplates.Tests"><code>Tests</code></a> plugin. It creates <code>runtests.jl</code>, but it also modifies the <code>Project.toml</code> to include the <code>Test</code> dependency.</p><p>Of course, we could use a normal <ahref="#PkgTemplates.Plugin"><code>Plugin</code></a>, but it turns out there's a way to avoid that while still getting the extra capbilities that we want.</p><p>The plugin implements its own <code>hook</code>, but uses <code>invoke</code> to avoid duplicating the file creation code:</p><pre><codeclass="language-julia">@with_kw_noshow struct Tests <: BasicPlugin
end</code></pre><p>There is also a default <ahref="#PkgTemplates.validate"><code>validate</code></a> implementation for <ahref="#PkgTemplates.BasicPlugin"><code>BasicPlugin</code></a>s, which checks that the plugin's <ahref="#PkgTemplates.source"><code>source</code></a> file exists, and throws an <code>ArgumentError</code> otherwise. If you want to extend the validation but keep the file existence check, use the <code>invoke</code> method as described above.</p><p>For more examples, see the plugins in the <ahref="../user/#Continuous-Integration-(CI)-1">Continuous Integration (CI)</a> and <ahref="../user/#Code-Coverage-1">Code Coverage</a> sections.</p><h2id="Miscellaneous-Tips-1"><aclass="docs-heading-anchor"href="#Miscellaneous-Tips-1">Miscellaneous Tips</a><aclass="docs-heading-anchor-permalink"href="#Miscellaneous-Tips-1"title="Permalink"></a></h2><h3id="Writing-Template-Files-1"><aclass="docs-heading-anchor"href="#Writing-Template-Files-1">Writing Template Files</a><aclass="docs-heading-anchor-permalink"href="#Writing-Template-Files-1"title="Permalink"></a></h3><p>For an overview of writing template files for Mustache.jl, see <ahref="../user/#Custom-Template-Files-1">Custom Template Files</a> in the user guide.</p><h3id="Predicates-1"><aclass="docs-heading-anchor"href="#Predicates-1">Predicates</a><aclass="docs-heading-anchor-permalink"href="#Predicates-1"title="Permalink"></a></h3><p>There are a few predicate functions for plugins that are occasionally used to answer questions like "does this <code>Template</code> have any code coverage plugins?". If you're implementing a plugin that fits into one of the following categories, it would be wise to implement the corresponding predicate function to return <code>true</code> for instances of your type.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.needs_username"href="#PkgTemplates.needs_username"><code>PkgTemplates.needs_username</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">needs_username(::Plugin) -> Bool</code></pre><p>Determine whether or not a plugin needs a Git hosting service username to function correctly. If you are implementing a plugin that uses the <code>user</code> field of a <ahref="../user/#PkgTemplates.Template"><code>Template</code></a>, you should implement this function and return <code>true</code>.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugin.jl#LL245-L251">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.is_ci"href="#PkgTemplates.is_ci"><code>PkgTemplates.is_ci</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">is_ci(::Plugin) -> Bool</code></pre><p>Determine whether or not a plugin is a CI plugin. If you are adding a CI plugin, you should implement this function and return <code>true</code>.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugins/ci.jl#LL398-L403">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.is_coverage"href="#PkgTemplates.is_coverage"><code>PkgTemplates.is_coverage</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">is_coverage(::Plugin) -> Bool</code></pre><p>Determine whether or not a plugin is a coverage plugin. If you are adding a coverage plugin, you should implement this function and return <code>true</code>.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ab9949a236c591f206c9d01753eb060cf92e5f5a/src/plugins/coverage.jl#LL53-L58">source</a></section></article><h3id="Formatting-Version-Numbers-1"><aclass="docs-heading-anchor"href=