<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>User Guide · PkgTemplates.jl</title><linkrel="canonical"href="https://invenia.github.io/PkgTemplates.jl/user/"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/fontawesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/solid.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/brands.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/katex.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL=".."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"data-main="../assets/documenter.js"></script><scriptsrc="../siteinfo.js"></script><scriptsrc="../../versions.js"></script><linkclass="docs-theme-link"rel="stylesheet"type="text/css"href="../assets/themes/documenter-dark.css"data-theme-name="documenter-dark"/><linkclass="docs-theme-link"rel="stylesheet"type="text/css"href="../assets/themes/documenter-light.css"data-theme-name="documenter-light"data-theme-primary/><scriptsrc="../assets/themeswap.js"></script></head><body><divid="documenter"><navclass="docs-sidebar"><divclass="docs-package-name"><spanclass="docs-autofit">PkgTemplates.jl</span></div><formclass="docs-search"action="../search/"><inputclass="docs-search-query"id="documenter-search-query"name="q"type="text"placeholder="Search docs"/></form><ulclass="docs-menu"><li><aclass="tocitem"href="../">Home</a></li><liclass="is-active"><aclass="tocitem"href>User Guide</a><ulclass="internal"><li><aclass="tocitem"href="#Template-1"><span>Template</span></a></li><li><aclass="tocitem"href="#Plugins-1"><span>Plugins</span></a></li><li><aclass="tocitem"href="#A-More-Complicated-Example-1"><span>A More Complicated Example</span></a></li><li><aclass="tocitem"href="#Custom-Template-Files-1"><span>Custom Template Files</span></a></li><li><aclass="tocitem"href="#Extending-Existing-Plugins-1"><span>Extending Existing Plugins</span></a></li><li><aclass="tocitem"href="#Saving-Templates-1"><span>Saving Templates</span></a></li></ul></li><li><aclass="tocitem"href="../developer/">Developer Guide</a></li><li><aclass="tocitem"href="../migrating/">Migrating To PkgTemplates 0.7+</a></li></ul><divclass="docs-version-selector field has-addons"><divclass="control"><spanclass="docs-label button is-static is-size-7">Version</span></div><divclass="docs-selector control is-expanded"><divclass="select is-fullwidth is-size-7"><selectid="documenter-version-selector"></select></div></div></div></nav><divclass="docs-main"><headerclass="docs-navbar"><navclass="breadcrumb"><ulclass="is-hidden-mobile"><liclass="is-active"><ahref>User Guide</a></li></ul><ulclass="is-hidden-tablet"><liclass="is-active"><ahref>User Guide</a></li></ul></nav><divclass="docs-right"><aclass="docs-edit-link"href="https://github.com/invenia/PkgTemplates.jl/blob/master/docs/src/user.md#L"title="Edit on GitHub"><spanclass="docs-icon fab"></span><spanclass="docs-label is-hidden-touch">Edit on GitHub</span></a><aclass="docs-settings-button fas fa-cog"id="documenter-settings-button"href="#"title="Settings"></a><aclass="docs-sidebar-button fa fa-bars is-hidden-desktop"id="documenter-sidebar-button"href="#"></a></div></header><articleclass="content"id="documenter-page"><h1id="PkgTemplates-User-Guide-1"><aclass="docs-heading-anchor"href="#PkgTemplates-User-Guide-1">PkgTemplates User Guide</a><aclass="docs-heading-anchor-permalink"href="#PkgTemplates-User-Guide-1"title="Permalink"></a></h1><ul><li><ahref="#PkgTemplates-User-Guide-1">PkgTemplates User Guide</a></li><ul><li><ahref="#Template-1">Template</a></li><li><ahref="#Plugins-1">Plugins</a></li><li><ahref="#A
t("MyPkg")</code></pre><h2id="Template-1"><aclass="docs-heading-anchor"href="#Template-1">Template</a><aclass="docs-heading-anchor-permalink"href="#Template-1"title="Permalink"></a></h2><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Template"href="#PkgTemplates.Template"><code>PkgTemplates.Template</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Template(; kwargs...)</code></pre><p>A configuration used to generate packages.</p><p><strong>Keyword Arguments</strong></p><p><strong>User Options</strong></p><ul><li><code>user::AbstractString="username"</code>: GitHub (or other code hosting service) username. The default value comes from the global Git config (<code>github.user</code>). If no value is obtained, many plugins that use this value will not work.</li><li><code>authors::Union{AbstractString, Vector{<:AbstractString}}="name <email> and contributors"</code>: Package authors. Like <code>user</code>, it takes its default value from the global Git config (<code>user.name</code> and <code>user.email</code>).</li></ul><p><strong>Package Options</strong></p><ul><li><code>dir::AbstractString="~/.julia/dev"</code>: Directory to place packages in.</li><li><code>host::AbstractString="github.com"</code>: URL to the code hosting service where packages will reside.</li><li><code>julia::VersionNumber=v"1.0.0"</code>: Minimum allowed Julia version.</li></ul><p><strong>Template Plugins</strong></p><ul><li><code>plugins::Vector{<:Plugin}=Plugin[]</code>: A list of <ahref="../developer/#PkgTemplates.Plugin"><code>Plugin</code></a>s used by the template. The default plugins are <ahref="#PkgTemplates.ProjectFile"><code>ProjectFile</code></a>, <ahref="#PkgTemplates.SrcDir"><code>SrcDir</code></a>, <ahref="#PkgTemplates.Tests"><code>Tests</code></a>, <ahref="#PkgTemplates.Readme"><code>Readme</code></a>, <ahref="#PkgTemplates.License"><code>License</code></a>, <ahref="#PkgTemplates.Git"><code>Git</code></a>, <ahref="#PkgTemplates.CompatHelper"><code>CompatHelper</code></a>, and <ahref="#PkgTemplates.TagBot"><code>TagBot</code></a>. To disable a default plugin, pass in the negated type: <code>!PluginType</code>. To override a default plugin instead of disabling it, pass in your own instance.</li></ul><p><strong>Interactive Mode</strong></p><ul><li><code>interactive::Bool=false</code>: In addition to specifying the template options with keywords, you can also build up a template by following a set of prompts. To create a template interactively, set this keyword to <code>true</code>. See also the similar <ahref="#PkgTemplates.generate"><code>generate</code></a> function.</li></ul><hr/><p>To create a package from a <code>Template</code>, use the following syntax:</p><pre><codeclass="language-julia">julia> t = Template();
julia> t("PkgName")</code></pre></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/d98579b7e72c08bdd0596d7b322eed225a62dd8a/src/template.jl#LL22-L65">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.generate"href="#PkgTemplates.generate"><code>PkgTemplates.generate</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">generate([pkg::AbstractString]) -> Template</code></pre><p>Shortcut for <code>Template(; interactive=true)(pkg)</code>. If no package name is supplied, you will be prompted for one.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/d98579b7e72c08bdd0596d7b322eed225a62dd8a/src/interactive.jl#LL1-L6">source</a></section></article><h2id="Plugins-1"><aclass="docs-heading-anchor"href="#Plugins-1">Plugins</a><aclass="docs-heading-anchor-permalink"href="#Plugins-1"title="Permalink"></a></h2><p>Plugins add functionality to <code>Template</code>s. There are a number of plugins available to automate common boilerplate tasks.</p><h3id="Default-Plugins-1"><aclass="docs-heading-anchor"href="#Default-Plugins-1">Default Plugins</a><aclass="docs-heading-anchor-permalink"href="#Default-Plugins-1"title="Permalink"></a></h3><p>These plugins are included by default. They can be overridden by supplying another value, or disabled by negating the type (<code>!Type</code>), both as elements of the <code>plugins</code> keyword.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.ProjectFile"href="#PkgTemplates.ProjectFile"><code>PkgTemplates.ProjectFile</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">ProjectFile(; version=v"0.1.0")</code></pre><p>Creates a <code>Project.toml</code>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>version::VersionNumber</code>: The initial version of created packages.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L7">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.SrcDir"href="#PkgTemplates.SrcDir"><code>PkgTemplates.SrcDir</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">SrcDir(; file="~/build/invenia/PkgTemplates.jl/templates/src/module.jl")</code></pre><p>Creates a module entrypoint.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for <code>src/<module>.jl</code>.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L7">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Tests"href="#PkgTemplates.Tests"><code>PkgTemplates.Tests</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Tests(; file="~/build/invenia/PkgTemplates.jl/templates/test/runtests.jl", project=false)</code></pre><p>Sets up testing for packages.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for <code>runtests.jl</code>.</li><li><code>project::Bool</code>: Whether or not to create a new project for tests (<code>test/Project.toml</code>). See <ahref="https://julialang.github.io/Pkg.jl/v1/creating-packages/#Test-specific-dependencies-in-Julia-1.2-and-above-1">here</a> for more details.</li></ul><divclass="admonition is-info"><headerclass="admonition-header">Note</header><divclass="admonition-body"><p>Managing test dependencies with <code>test/Project.toml</code> is only supported in Julia 1.2 and later.</p></div></div></div><aclass="docs-sourcelink"target="_blan
)</code></pre><p>Creates a <code>README</code> file that contains badges for other included plugins.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for the <code>README</code>.</li><li><code>destination::AbstractString</code>: File destination, relative to the repository root. For example, values of <code>"README"</code> or <code>"README.rst"</code> might be desired.</li><li><code>inline_badges::Bool</code>: Whether or not to put the badges on the same line as the package name.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L14">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.License"href="#PkgTemplates.License"><code>PkgTemplates.License</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">License(; name="MIT", path=nothing, destination="LICENSE")</code></pre><p>Creates a license file.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>name::AbstractString</code>: Name of a license supported by PkgTemplates. Available licenses can be seen <ahref="https://github.com/invenia/PkgTemplates.jl/tree/master/templates/licenses">here</a>.</li><li><code>path::Union{AbstractString, Nothing}</code>: Path to a custom license file. This keyword takes priority over <code>name</code>.</li><li><code>destination::AbstractString</code>: File destination, relative to the repository root. For example, <code>"LICENSE.md"</code> might be desired.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/d98579b7e72c08bdd0596d7b322eed225a62dd8a/src/plugins/license.jl#LL1-L14">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Git"href="#PkgTemplates.Git"><code>PkgTemplates.Git</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Git(;
)</code></pre><p>Creates a Git repository and a <code>.gitignore</code> file.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>ignore::Vector{<:AbstractString}</code>: Patterns to add to the <code>.gitignore</code>. See also: <ahref="../developer/#PkgTemplates.gitignore"><code>gitignore</code></a>.</li><li><code>name::AbstractString</code>: Your real name, if you have not set <code>user.name</code> with Git.</li><li><code>email::AbstractString</code>: Your email address, if you have not set <code>user.email</code> with Git.</li><li><code>ssh::Bool</code>: Whether or not to use SSH for the remote. If left unset, HTTPS is used.</li><li><code>jl::Bool</code>: Whether or not to add a <code>.jl</code> suffix to the remote URL.</li><li><code>manifest::Bool</code>: Whether or not to commit <code>Manifest.toml</code>.</li><li><code>gpgsign::Bool</code>: Whether or not to sign commits with your GPG key. This option requires that the Git CLI is installed, and for you to have a GPG key associated with your committer identity.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L25">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.CompatHelper"href="#PkgTemplates.CompatHelper"><code>PkgTemplates.CompatHelper</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">CompatHelper(;
)</code></pre><p>Integrates your packages with <ahref="https://github.com/bcbi/CompatHelper.jl">CompatHelper</a> via GitHub Actions.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for the workflow file.</li><li><code>destination::AbstractString</code>: Destination of the workflow file, relative to <code>.github/workflows</code>.</li><li><code>cron::AbstractString</code>: Cron expression for the schedule interval.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L14">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.TagBot"href="#PkgTemplates.TagBot"><code>PkgTemplates.TagBot</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">TagBot(;
)</code></pre><p>Adds GitHub release support via <ahref="https://github.com/JuliaRegistries/TagBot">TagBot</a>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for the workflow file.</li><li><code>destination::AbstractString</code>: Destination of the workflow file, relative to <code>.github/workflows</code>.</li><li><code>cron::AbstractString</code>: Cron expression for the schedule interval.</li><li><code>token::Secret</code>: Name of the token secret to use.</li><li><code>ssh::Secret</code>: Name of the SSH private key secret to use.</li><li><code>ssh_password::Secret</code>: Name of the SSH key password secret to use.</li><li><code>changelog::AbstractString</code>: Custom changelog template.</li><li><code>changelog_ignore::Vector{<:AbstractString}</code>: Issue/pull request labels to ignore in the changelog.</li><li><code>gpg::Secret</code>: Name of the GPG private key secret to use.</li><li><code>gpg_password::Secret</code>: Name of the GPG private key password secret to use.</li><li><code>registry::AbstractString</code>: Custom registry, in the format <code>owner/repo</code>.</li><li><code>branches::Bool</code>: Whether not to enable the <code>branches</code> option.</li><li><code>dispatch::Bool</code>: Whether or not to enable the <code>dispatch</code> option.</li><li><code>dispatch_delay::Int</code>: Number of minutes to delay for dispatch events.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L35">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Secret"href="#PkgTemplates.Secret"><code>PkgTemplates.Secret</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Secret(name::AbstractString)</code></pre><p>Represents a GitHub repository secret. When converted to a string, yields <code>${{ secrets.<name> }}</code>.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/d98579b7e72c08bdd0596d7b322eed225a62dd8a/src/plugin.jl#LL87-L92">source</a></section></article><h3id="Continuous-Integration-(CI)-1"><aclass="docs-heading-anchor"href="#Continuous-Integration-(CI)-1">Continuous Integration (CI)</a><aclass="docs-heading-anchor-permalink"href="#Continuous-Integration-(CI)-1"title="Permalink"></a></h3><p>These plugins will create the configuration files of common CI services for you.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.AppVeyor"href="#PkgTemplates.AppVeyor"><code>PkgTemplates.AppVeyor</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">AppVeyor(;
)</code></pre><p>Integrates your packages with <ahref="https://appveyor.com">AppVeyor</a> via <ahref="https://github.com/JuliaCI/Appveyor.jl">AppVeyor.jl</a>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for <code>.appveyor.yml</code>.</li><li><code>x86::Bool</code>: Whether or not to run builds on 32-bit systems, in addition to the default 64-bit builds.</li><li><code>coverage::Bool</code>: Whether or not to publish code coverage. <ahref="#PkgTemplates.Codecov"><code>Codecov</code></a> must also be included.</li><li><code>extra_versions::Vector</code>: Extra Julia versions to test, as strings or <code>VersionNumber</code>s.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L18">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.CirrusCI"href="#PkgTemplates.CirrusCI"><code>PkgTemplates.CirrusCI</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">CirrusCI(;
)</code></pre><p>Integrates your packages with <ahref="https://cirrus-ci.org">Cirrus CI</a> via <ahref="https://github.com/ararslan/CirrusCI.jl">CirrusCI.jl</a>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for <code>.cirrus.yml</code>.</li><li><code>image::AbstractString</code>: The FreeBSD image to be used.</li><li><code>coverage::Bool</code>: Whether or not to publish code coverage. <ahref="#PkgTemplates.Codecov"><code>Codecov</code></a> must also be included.</li><li><code>extra_versions::Vector</code>: Extra Julia versions to test, as strings or <code>VersionNumber</code>s.</li></ul><divclass="admonition is-info"><headerclass="admonition-header">Note</header><divclass="admonition-body"><p>Code coverage submission from Cirrus CI is not yet supported by <ahref="https://github.com/JuliaCI/Coverage.jl">Coverage.jl</a>.</p></div></div></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L21">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.DroneCI"href="#PkgTemplates.DroneCI"><code>PkgTemplates.DroneCI</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">DroneCI(;
)</code></pre><p>Integrates your packages with <ahref="https://drone.io">Drone CI</a>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for <code>.drone.star</code>.</li><li><code>destination::AbstractString</code>: File destination, relative to the repository root. For example, you might want to generate a <code>.drone.yml</code> instead of the default Starlark file.</li><li><code>amd64::Bool</code>: Whether or not to run builds on AMD64.</li><li><code>arm::Bool</code>: Whether or not to run builds on ARM (32-bit).</li><li><code>arm64::Bool</code>: Whether or not to run builds on ARM64.</li><li><code>extra_versions::Vector</code>: Extra Julia versions to test, as strings or <code>VersionNumber</code>s.</li></ul><divclass="admonition is-info"><headerclass="admonition-header">Note</header><divclass="admonition-body"><p>Nightly Julia is not supported.</p></div></div></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L22">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.GitHubActions"href="#PkgTemplates.GitHubActions"><code>PkgTemplates.GitHubActions</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">GitHubActions(;
)</code></pre><p>Integrates your packages with <ahref="https://github.com/features/actions">GitHub Actions</a>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for the workflow file.</li><li><code>destination::AbstractString</code>: Destination of the workflow file, relative to <code>.github/workflows</code>.</li><li><code>linux::Bool</code>: Whether or not to run builds on Linux.</li><li><code>osx::Bool</code>: Whether or not to run builds on OSX (MacOS).</li><li><code>windows::Bool</code>: Whether or not to run builds on Windows.</li><li><code>x64::Bool</code>: Whether or not to run builds on 64-bit architecture.</li><li><code>x86::Bool</code>: Whether or not to run builds on 32-bit architecture.</li><li><code>coverage::Bool</code>: Whether or not to publish code coverage. Another code coverage plugin such as <ahref="#PkgTemplates.Codecov"><code>Codecov</code></a> must also be included.</li><li><code>extra_versions::Vector</code>: Extra Julia versions to test, as strings or <code>VersionNumber</code>s.</li></ul><divclass="admonition is-info"><headerclass="admonition-header">Note</header><divclass="admonition-body"><p>If using coverage plugins, don't forget to manually add your API tokens as secrets, as described <ahref="https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets">here</a>.</p></div></div></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L31">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.GitLabCI"href="#PkgTemplates.GitLabCI"><code>PkgTemplates.GitLabCI</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">GitLabCI(;
)</code></pre><p>Integrates your packages with <ahref="https://docs.gitlab.com/ce/ci">GitLab CI</a>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for <code>.gitlab-ci.yml</code>.</li><li><code>coverage::Bool</code>: Whether or not to compute code coverage.</li><li><code>extra_versions::Vector</code>: Extra Julia versions to test, as strings or <code>VersionNumber</code>s.</li></ul><p><strong>GitLab Pages</strong></p><p>Documentation can be generated by including a <code>Documenter{GitLabCI}</code> plugin. See <ahref="#PkgTemplates.Documenter"><code>Documenter</code></a> for more information.</p><divclass="admonition is-info"><headerclass="admonition-header">Note</header><divclass="admonition-body"><p>Nightly Julia is not supported.</p></div></div></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L20">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.TravisCI"href="#PkgTemplates.TravisCI"><code>PkgTemplates.TravisCI</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">TravisCI(;
)</code></pre><p>Integrates your packages with <ahref="https://travis-ci.com">Travis CI</a>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for <code>.travis.yml</code>.</li><li><code>linux::Bool</code>: Whether or not to run builds on Linux.</li><li><code>osx::Bool</code>: Whether or not to run builds on OSX (MacOS).</li><li><code>windows::Bool</code>: Whether or not to run builds on Windows.</li><li><code>x64::Bool</code>: Whether or not to run builds on 64-bit architecture.</li><li><code>x86::Bool</code>: Whether or not to run builds on 32-bit architecture.</li><li><code>arm64::Bool</code>: Whether or not to run builds on the ARM64 architecture.</li><li><code>coverage::Bool</code>: Whether or not to publish code coverage. Another code coverage plugin such as <ahref="#PkgTemplates.Codecov"><code>Codecov</code></a> must also be included.</li><li><code>extra_versions::Vector</code>: Extra Julia versions to test, as strings or <code>VersionNumber</code>s.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L26">source</a></section></article><h3id="Code-Coverage-1"><aclass="docs-heading-anchor"href="#Code-Coverage-1">Code Coverage</a><aclass="docs-heading-anchor-permalink"href="#Code-Coverage-1"title="Permalink"></a></h3><p>These plugins will enable code coverage reporting from CI.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Codecov"href="#PkgTemplates.Codecov"><code>PkgTemplates.Codecov</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Codecov(; file=nothing)</code></pre><p>Sets up code coverage submission from CI to <ahref="https://codecov.io">Codecov</a>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::Union{AbstractString, Nothing}</code>: Template file for <code>.codecov.yml</code>, or <code>nothing</code> to create no file.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L8">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Coveralls"href="#PkgTemplates.Coveralls"><code>PkgTemplates.Coveralls</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Coveralls(; file=nothing)</code></pre><p>Sets up code coverage submission from CI to <ahref="https://coveralls.io">Coveralls</a>.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::Union{AbstractString, Nothing}</code>: Template file for <code>.coveralls.yml</code>, or <code>nothing</code> to create no file.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base/#L0-L8">source</a></section></article><h3id="Documentation-1"><aclass="docs-heading-anchor"href="#Documentation-1">Documentation</a><aclass="docs-heading-anchor-permalink"href="#Documentation-1"title="Permalink"></a></h3><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Documenter"href="#PkgTemplates.Documenter"><code>PkgTemplates.Documenter</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Documenter{T<:Union{TravisCI, GitLabCI, GitHubActions, NoDeploy}}(;
)</code></pre><p>Sets up documentation generation via <ahref="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a>. Documentation deployment depends on <code>T</code>, where <code>T</code> is some supported CI plugin, or <code>Nothing</code> to only support local documentation builds.</p><p><strong>Supported Type Parameters</strong></p><ul><li><code>GitHubActions</code>: Deploys documentation to <ahref="https://pages.github.com">GitHub Pages</a> with the help of <ahref="#PkgTemplates.GitHubActions"><code>GitHubActions</code></a>.</li><li><code>TravisCI</code>: Deploys documentation to <ahref="https://pages.github.com">GitHub Pages</a> with the help of <ahref="#PkgTemplates.TravisCI"><code>TravisCI</code></a>.</li><li><code>GitLabCI</code>: Deploys documentation to <ahref="https://pages.gitlab.com">GitLab Pages</a> with the help of <ahref="#PkgTemplates.GitLabCI"><code>GitLabCI</code></a>.</li><li><code>NoDeploy</code> (default): Does not set up documentation deployment.</li></ul><p><strong>Keyword Arguments</strong></p><ul><li><code>make_jl::AbstractString</code>: Template file for <code>make.jl</code>.</li><li><code>index_md::AbstractString</code>: Template file for <code>index.md</code>.</li><li><code>assets::Vector{<:AbstractString}</code>: Extra assets for the generated site.</li><li><code>canonical_url::Union{Function, Nothing}</code>: A function to generate the site's canonical URL. The default value will compute GitHub Pages and GitLab Pages URLs for <ahref="#PkgTemplates.TravisCI"><code>TravisCI</code></a> and <ahref="#PkgTemplates.GitLabCI"><code>GitLabCI</code></a>, respectively. If set to <code>nothing</code>, no canonical URL is set.</li><li><code>makedocs_kwargs::Dict{Symbol}</code>: Extra keyword arguments to be inserted into <code>makedocs</code>.</li></ul><divclass="admonition is-info"><headerclass="admonition-header">Note</header><divclass="admonition-body"><p>If deploying documentation with Travis CI, don't forget to complete <ahref="https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#SSH-Deploy-Keys-1">the required configuration</a>.</p></div></div></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/d98579b7e72c08bdd0596d7b322eed225a62dd8a/src/plugins/documenter.jl#LL10-L45">source</a></section></article><h3id="Miscellaneous-1"><aclass="docs-heading-anchor"href="#Miscellaneous-1">Miscellaneous</a><aclass="docs-heading-anchor-permalink"href="#Miscellaneous-1"title="Permalink"></a></h3><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Develop"href="#PkgTemplates.Develop"><code>PkgTemplates.Develop</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Develop()</code></pre><p>Adds generated packages to the current environment by <code>dev</code>ing them. See the Pkg documentation <ahref="https://julialang.github.io/Pkg.jl/v1/managing-packages/#Developing-packages-1">here</a> for more details.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/d98579b7e72c08bdd0596d7b322eed225a62dd8a/src/plugins/develop.jl#LL1-L8">source</a></section></article><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.Citation"href="#PkgTemplates.Citation"><code>PkgTemplates.Citation</code></a> — <spanclass="docstring-category">Type</span></header><section><div><pre><codeclass="language-julia">Citation(; file="~/build/invenia/PkgTemplates.jl/templates/CITATION.bib", readme=false)</code></pre><p>Creates a <code>CITATION.bib</code> file for citing package repositories.</p><p><strong>Keyword Arguments</strong></p><ul><li><code>file::AbstractString</code>: Template file for <code>CITATION.bib</code>.</li><li><code>readme::Bool</code>: Whether or not to include a section about citing in the README.</li></ul></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/JuliaLang/julia/blob/44fa15b1502a45eac76c9017af94332d4557b251/base
)</code></pre><h2id="Custom-Template-Files-1"><aclass="docs-heading-anchor"href="#Custom-Template-Files-1">Custom Template Files</a><aclass="docs-heading-anchor-permalink"href="#Custom-Template-Files-1"title="Permalink"></a></h2><divclass="admonition is-info"><headerclass="admonition-header">Templates vs Templating</header><divclass="admonition-body"><p>This documentation refers plenty to <ahref="#PkgTemplates.Template"><code>Template</code></a>s, the package's main type, but it also refers to "template files" and "text templating", which are plaintext files with placeholders to be filled with data, and the technique of filling those placeholders with data, respectively.</p><p>These concepts should be familiar if you've used <ahref="https://palletsprojects.com/p/jinja">Jinja</a> or <ahref="https://mustache.github.io">Mustache</a> (Mustache is the particular flavour used by PkgTemplates, via <ahref="https://github.com/jverzani/Mustache.jl">Mustache.jl</a>). Please keep the difference between these two things in mind!</p></div></div><p>Many plugins support a <code>file</code> argument or similar, which sets the path to the template file to be used for generating files. Each plugin has a sensible default that should make sense for most people, but you might have a specialized workflow that requires a totally different template file.</p><p>If that's the case, a basic understanding of <ahref="https://mustache.github.io">Mustache</a>'s syntax is required. Here's an example template file:</p><pre><codeclass="language-none">Hello, {{{name}}}.
{{/people}}</code></pre><p>In the first section, <code>name</code> is a key, and its value replaces <code>{{{name}}}</code>.</p><p>In the second section, <code>weather</code>'s value may or may not exist. If it does exist, then "It's weather outside" is printed. Otherwise, "I don't know what the weather outside is" is printed. Mustache uses a notion of "truthiness" similar to Python or JavaScript, where values of <code>nothing</code>, <code>false</code>, or empty collections are all considered to not exist.</p><p>In the third section, <code>has_things</code>' value is printed if it's truthy. Then, if the <code>things</code> list is truthy (i.e. not empty), its values are each printed on their own line. The reason that we have two separate keys is that <code>{{#things}}</code> iterates over the whole <code>things</code> list, even when there are no <code>{{{.}}}</code> placeholders, which would duplicate "I have the following things:"<code>n</code> times.</p><p>The fourth section iterates over the <code>people</code> list, but instead of using the <code>{{{.}}}</code> placeholder, we have <code>name</code> and <code>mood</code>, which are keys or fields of the list elements. Most types are supported here, including <code>Dict</code>s and structs. <code>NamedTuple</code>s require you to use <code>{{{:name}}}</code> instead of the normal <code>{{{name}}}</code>, though.</p><p>You might notice that some curlies are in groups of two (<code>{{key}}</code>), and some are in groups of three (<code>{{{key}}}</code>). Whenever we want to subtitute in a value, using the triple curlies disables HTML escaping, which we rarely want for the types of files we're creating. If you do want escaping, just use the double curlies. And if you're using different delimiters, for example <code><<foo>></code>, use <code><<&foo>></code> to disable escaping.</p><p>Assuming the following view:</p><pre><codeclass="language-julia">struct Person; name::String; mood::String; end
things = ["a", "b", "c"]
- Jane is sad</code></pre><h2id="Extending-Existing-Plugins-1"><aclass="docs-heading-anchor"href="#Extending-Existing-Plugins-1">Extending Existing Plugins</a><aclass="docs-heading-anchor-permalink"href="#Extending-Existing-Plugins-1"title="Permalink"></a></h2><p>Most of the existing plugins generate a file from a template file. If you want to use custom template files, you may run into situations where the data passed into the templating engine is not sufficient. In this case, you can look into implementing <ahref="#PkgTemplates.user_view"><code>user_view</code></a> to supply whatever data is necessary for your use case.</p><articleclass="docstring"><header><aclass="docstring-binding"id="PkgTemplates.user_view"href="#PkgTemplates.user_view"><code>PkgTemplates.user_view</code></a> — <spanclass="docstring-category">Function</span></header><section><div><pre><codeclass="language-julia">user_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}</code></pre><p>The same as <ahref="../developer/#PkgTemplates.view"><code>view</code></a>, but for use by package <em>users</em> for extension.</p><p>Values returned by this function will override those from <ahref="../developer/#PkgTemplates.view"><code>view</code></a> when the keys are the same.</p></div><aclass="docs-sourcelink"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/d98579b7e72c08bdd0596d7b322eed225a62dd8a/src/plugin.jl#LL127-L134">source</a></section></article><p>For example, suppose you were using the <ahref="#PkgTemplates.Readme"><code>Readme</code></a> plugin with a custom template file that looked like this:</p><pre><codeclass="language-md"># {{PKG}}
Created on *{{TODAY}}*.</code></pre><p>The <ahref="../developer/#PkgTemplates.view"><code>view</code></a> function supplies a value for <code>PKG</code>, but it does not supply a value for <code>TODAY</code>. Rather than override <ahref="../developer/#PkgTemplates.view"><code>view</code></a>, we can implement this function to get both the default values and whatever else we need to add.</p><pre><codeclass="language-julia">user_view(::Readme, ::Template, ::AbstractString) = Dict("TODAY" => today())</code></pre><h2id="Saving-Templates-1"><aclass="docs-heading-anchor"href="#Saving-Templates-1">Saving Templates</a><aclass="docs-heading-anchor-permalink"href="#Saving-Templates-1"title="Permalink"></a></h2><p>One of the main reasons for PkgTemplates' existence is for new packages to be consistent. This means using the same template more than once, so we want a way to save a template to be used later.</p><p>Here's my recommendation for loading a template whenever it's needed:</p><pre><codeclass="language-julia">function template()
end</code></pre><p>Add this to your <code>startup.jl</code>, and you can create your template from anywhere, without incurring any startup cost.</p><p>Another strategy is to write the string representation of the template to a Julia file:</p><pre><codeclass="language-julia">const t = Template(; #= ... =#)
open("template.jl", "w") do io
println(io, "using PkgTemplates")
sprint(show, io, t)
end</code></pre><p>Then the template is just an <code>include</code> away:</p><pre><codeclass="language-julia">const t = include("template.jl")</code></pre><p>The only disadvantage to this approach is that the saved template is much less human-readable than code you wrote yourself.</p><p>One more method of saving templates is to simply use the Serialization package in the standard library:</p><pre><codeclass="language-julia">const t = Template(; #= ... =#)
const t = open(deserialize, "template.bin")</code></pre><p>This approach has the same disadvantage as the previous one, and the serialization format is not guaranteed to be stable across Julia versions.</p></article><navclass="docs-footer"><aclass="docs-footer-prevpage"href="../">« Home</a><aclass="docs-footer-nextpage"href="../developer/">Developer Guide »</a></nav></div><divclass="modal"id="documenter-settings"><divclass="modal-background"></div><divclass="modal-card"><headerclass="modal-card-head"><pclass="modal-card-title">Settings</p><buttonclass="delete"></button></header><sectionclass="modal-card-body"><p><labelclass="label">Theme</label><divclass="select"><selectid="documenter-themepicker"><optionvalue="documenter-light">documenter-light</option><optionvalue="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <ahref="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> on <spanclass="colophon-date"title="Thursday 28 May 2020 15:10">Thursday 28 May 2020</span>. Using Julia version 1.4.2.</p></section><footerclass="modal-card-foot"></footer></div></div></div></body></html>
