Records common information used to generate a package. If you don't wish to manually create a template, you can use interactive_template instead.
Keyword Arguments
user::AbstractString="": GitHub username. If left unset, it will try to take the value of a supplied git config's "github.user" key, then the global git config's value. If neither is set, an ArgumentError is thrown. This is case-sensitive for some plugins, so take care to enter it correctly.
host::AbstractString="github.com": URL to the code hosting service where your package will reside. Note that while hosts other than GitHub won't cause errors, they are not officially supported and they will cause certain plugins will produce incorrect output. For example, AppVeyor's badge image will point to a GitHub-specific URL, regardless of the value of host.
license::AbstractString="MIT": Name of the package license. If an empty string is given, no license is created. available_licenses can be used to list all available licenses, and show_license can be used to print out a particular license's text.
authors::Union{AbstractString, Vector{<:AbstractString}}="": Names that appear on the license. Supply a string for one author or an array for multiple. Similarly to user, it will try to take the value of a supplied git config's "user.name" key, then the global git config's value, if it is left unset.
years::Union{Integer, AbstractString}=Dates.year(Dates.today()): Copyright years on the license. Can be supplied by a number, or a string such as "2016 - 2017".
dir::AbstractString=Pkg.dir(): Directory in which the package will go. Relative paths are converted to absolute ones at template creation time.
precompile::Bool=true: Whether or not to enable precompilation in generated packages.
julia_version::VersionNumber=VERSION: Minimum allowed Julia version.
requirements::Vector{<:AbstractString}=String[]: Package requirements. If there are duplicate requirements with different versions, i.e. ["PkgTemplates", "PkgTemplates 0.1"], an ArgumentError is thrown. Each entry in this array will be copied into the REQUIRE file of packages generated with this template.
Records common information used to generate a package. If you don't wish to manually create a template, you can use interactive_template instead.
Keyword Arguments
user::AbstractString="": GitHub username. If left unset, it will try to take the value of a supplied git config's "github.user" key, then the global git config's value. If neither is set, an ArgumentError is thrown. This is case-sensitive for some plugins, so take care to enter it correctly.
host::AbstractString="github.com": URL to the code hosting service where your package will reside. Note that while hosts other than GitHub won't cause errors, they are not officially supported and they will cause certain plugins will produce incorrect output. For example, AppVeyor's badge image will point to a GitHub-specific URL, regardless of the value of host.
license::AbstractString="MIT": Name of the package license. If an empty string is given, no license is created. available_licenses can be used to list all available licenses, and show_license can be used to print out a particular license's text.
authors::Union{AbstractString, Vector{<:AbstractString}}="": Names that appear on the license. Supply a string for one author or an array for multiple. Similarly to user, it will try to take the value of a supplied git config's "user.name" key, then the global git config's value, if it is left unset.
years::Union{Integer, AbstractString}=Dates.year(Dates.today()): Copyright years on the license. Can be supplied by a number, or a string such as "2016 - 2017".
dir::AbstractString=Pkg.dir(): Directory in which the package will go. Relative paths are converted to absolute ones at template creation time.
precompile::Bool=true: Whether or not to enable precompilation in generated packages.
julia_version::VersionNumber=VERSION: Minimum allowed Julia version.
requirements::Vector{<:AbstractString}=String[]: Package requirements. If there are duplicate requirements with different versions, i.e. ["PkgTemplates", "PkgTemplates 0.1"], an ArgumentError is thrown. Each entry in this array will be copied into the REQUIRE file of packages generated with this template.
force::Bool=false: Whether or not to overwrite old packages with the same name.
ssh::Bool=false: Whether or not to use SSH for the remote.
backup_dir::AbstractString="": Directory in which to store the generated package if t.dir is not a valid directory. If left unset, a temporary directory will be created (this keyword is mostly for internal usage).
Notes
The package is generated entirely in a temporary directory and only moved into joinpath(t.dir, pkg_name) at the very end. In the case of an error, the temporary directory will contain leftovers, but the destination directory will remain untouched (this is especially helpful when force=true).
force::Bool=false: Whether or not to overwrite old packages with the same name.
ssh::Bool=false: Whether or not to use SSH for the remote.
backup_dir::AbstractString="": Directory in which to store the generated package if t.dir is not a valid directory. If left unset, a temporary directory will be created (this keyword is mostly for internal usage).
Notes
The package is generated entirely in a temporary directory and only moved into joinpath(t.dir, pkg_name) at the very end. In the case of an error, the temporary directory will contain leftovers, but the destination directory will remain untouched (this is especially helpful when force=true).
Interactively create a template, and then generate a package with it. Arguments and keywords are used in the same way as in generate and interactive_template.
Interactively create a template, and then generate a package with it. Arguments and keywords are used in the same way as in generate and interactive_template.
A plugin to be added to a Template, which adds some functionality or integration. New plugins should almost always extend GenericPlugin or CustomPlugin.
Generic plugins are plugins that add any number of patterns to the generated package's .gitignore, and have at most one associated file to generate.
Attributes
gitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.
src::Nullable{AbstractString}: Path to the file that will be copied into the generated package repository. If set to nothing, no file will be generated. When this defaults to an empty string, there should be a default file in defaults that will be copied. That file's name is usually the same as the plugin's name, except in all lowercase and with the .yml extension. If this is not the case, an interactive method needs to be implemented to call interactive(; file="file.ext").
dest::AbstractString: Path to the generated file, relative to the root of the generated package repository.
badges::Vector{Badge}: Array of Badges containing information used to create Markdown-formatted badges from the plugin. Entries will be run through substitute, so they may contain placeholder values.
view::Dict{String, Any}: Additional substitutions to make in both the plugin's badges and its associated file. See substitute for details.
Example
@auto_hash_equals struct MyPlugin <: GenericPlugin
+Plugin Development · PkgTemplates.jl
A plugin to be added to a Template, which adds some functionality or integration. New plugins should almost always extend GenericPlugin or CustomPlugin.
Generic plugins are plugins that add any number of patterns to the generated package's .gitignore, and have at most one associated file to generate.
Attributes
gitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.
src::Nullable{AbstractString}: Path to the file that will be copied into the generated package repository. If set to nothing, no file will be generated. When this defaults to an empty string, there should be a default file in defaults that will be copied. That file's name is usually the same as the plugin's name, except in all lowercase and with the .yml extension. If this is not the case, an interactive method needs to be implemented to call interactive(; file="file.ext").
dest::AbstractString: Path to the generated file, relative to the root of the generated package repository.
badges::Vector{Badge}: Array of Badges containing information used to create Markdown-formatted badges from the plugin. Entries will be run through substitute, so they may contain placeholder values.
view::Dict{String, Any}: Additional substitutions to make in both the plugin's badges and its associated file. See substitute for details.
Example
@auto_hash_equals struct MyPlugin <: GenericPlugin
gitignore::Vector{AbstractString}
src::Nullable{AbstractString}
dest::AbstractString
@@ -34,7 +34,7 @@
end
end
-interactive(plugin_type::Type{MyPlugin}) = interactive(plugin_type; file="my-plugin.toml")
The above plugin ignores files ending with .mgp, copies defaults/my-plugin.toml by default, and creates a badge that links to the project on its own site, using the default substitutions with one addition: {{YEAR}} => Dates.year(Dates.today()). Since the default config template file doesn't follow the generic naming convention, we added another interactive method to correct the assumed filename.
Custom plugins are plugins whose behaviour does not follow the GenericPlugin pattern. They can implement gen_plugin, badges, and interactive in any way they choose.
Attributes
gitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.
The above plugin ignores files ending with .mgp, copies defaults/my-plugin.toml by default, and creates a badge that links to the project on its own site, using the default substitutions with one addition: {{YEAR}} => Dates.year(Dates.today()). Since the default config template file doesn't follow the generic naming convention, we added another interactive method to correct the assumed filename.
Custom plugins are plugins whose behaviour does not follow the GenericPlugin pattern. They can implement gen_plugin, badges, and interactive in any way they choose.
Attributes
gitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.
Example
@auto_hash_equals struct MyPlugin <: CustomPlugin
gitignore::Vector{AbstractString}
lucky::Bool
@@ -76,16 +76,17 @@ interactive(plugin_type::Type{MyPlugin}) = interactive(plugin_type; file="m
end
end
-interactive(plugin_type::Type{MyPlugin}) = MyPlugin()
Often, the contents of the config file that your plugin generates depends on variables like the package name, the user's username, etc. Template files (which are stored in defaults) can use here's syntax to define replacements.
Note: Due to a bug in Mustache, conditionals can insert undesired newlines (more detail here).
Often, the contents of the config file that your plugin generates depends on variables like the package name, the user's username, etc. Template files (which are stored in defaults) can use here's syntax to define replacements.
Note: Due to a bug in Mustache, conditionals can insert undesired newlines (more detail here).
Interactively create a plugin of type plugin_type, where file is the plugin type's default config template with a non-standard name (for MyPlugin, this is anything but "myplugin.yml").
Note: interactive is not strictly required, however without it, your custom plugin will not be available when creating templates with interactive_template.
Interactively create a plugin of type plugin_type, where file is the plugin type's default config template with a non-standard name (for MyPlugin, this is anything but "myplugin.yml").
Note: interactive is not strictly required, however without it, your custom plugin will not be available when creating templates with interactive_template.
Replace placeholders in template with values in view via Mustache. template is not modified. If pkg_template is supplied, some default replacements are also performed.
For information on how to structure template, see "Defining Template Files" section in Custom Plugins.
Note: Conditionals in template without a corresponding key in view won't error, but will simply be evaluated as false.
Plugins are the secret sauce behing PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development.
Add CodeCov to a template's plugins to optionally add a .codecov.yml configuration file to generated repositories, and an appropriate badge to the README. Also updates the .gitignore accordingly.
Keyword Arguments:
config_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.
Add Coveralls to a template's plugins to optionally add a .coveralls.yml configuration file to generated repositories, and an appropriate badge to the README. Also updates the .gitignore accordingly.
Keyword Arguments:
config_file::Union{AbstractString, Void}=nothing: Path to a custom .coveralls.yml. If left unset, no file will be generated.
Add GitHubPages to a template's plugins to add Documenter support via GitHub Pages, including automatic uploading of documentation from TravisCI. Also adds appropriate badges to the README, and updates the .gitignore accordingly.
Keyword Arguments
assets::Vector{<:AbstractString}=String[]: Array of paths to Documenter asset files.
Plugins are the secret sauce behing PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development.
Add CodeCov to a template's plugins to optionally add a .codecov.yml configuration file to generated repositories, and an appropriate badge to the README. Also updates the .gitignore accordingly.
Keyword Arguments:
config_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.
Add Coveralls to a template's plugins to optionally add a .coveralls.yml configuration file to generated repositories, and an appropriate badge to the README. Also updates the .gitignore accordingly.
Keyword Arguments:
config_file::Union{AbstractString, Void}=nothing: Path to a custom .coveralls.yml. If left unset, no file will be generated.
Add GitHubPages to a template's plugins to add Documenter support via GitHub Pages, including automatic uploading of documentation from TravisCI. Also adds appropriate badges to the README, and updates the .gitignore accordingly.
Keyword Arguments
assets::Vector{<:AbstractString}=String[]: Array of paths to Documenter asset files.
source
diff --git a/latest/search_index.js b/latest/search_index.js
index 790ea2d..75fd35a 100644
--- a/latest/search_index.js
+++ b/latest/search_index.js
@@ -389,7 +389,7 @@ var documenterSearchIndex = {"docs": [
"page": "Plugin Development",
"title": "PkgTemplates.substitute",
"category": "Function",
- "text": "substitute(template::AbstractString, view::Dict{String, Any}) -> String\n\nReplace placeholders in template with values in view via Mustache. template is not modified.\n\nFor information on how to structure template, see \"Defining Template Files\" section in Custom Plugins.\n\nNote: Conditionals in template without a corresponding key in view won't error, but will simply be evaluated as false.\n\n\n\nsubstitute(\n template::AbstractString,\n pkg_template::Template;\n view::Dict{String, Any}=Dict{String, Any}(),\n) -> String\n\nReplace placeholders in template, using some default replacements based on the pkg_template and additional ones in view. template is not modified.\n\n\n\n"
+ "text": "substitute(template::AbstractString, view::Dict{String, Any}) -> String\nsubstitute(\n template::AbstractString,\n pkg_template::Template;\n view::Dict{String, Any}=Dict{String, Any}(),\n) -> String\n\nReplace placeholders in template with values in view via Mustache. template is not modified. If pkg_template is supplied, some default replacements are also performed.\n\nFor information on how to structure template, see \"Defining Template Files\" section in Custom Plugins.\n\nNote: Conditionals in template without a corresponding key in view won't error, but will simply be evaluated as false.\n\n\n\n"
},
{