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 (or other code hosting service) username. If left unset, it will take the the global git config's value (github.user). If that is not 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.
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 take the value of of the global git config's value if it is left unset.
dir::AbstractString=~/.julia/dev: Directory in which the package will go. Relative paths are converted to absolute ones at template creation time.
julia_version::VersionNumber=1.0.0: Minimum allowed Julia version.
ssh::Bool=false: Whether or not to use SSH for the git remote. If false HTTPS will be used.
dev::Bool=true: Whether or not to Pkg.develop generated packages.
manifest::Bool=false: Whether or not to commit the Manifest.toml.
plugins::Vector{<:Plugin}=Plugin[]: A list of Plugins that the package will include.
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.
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 (or other code hosting service) username. If left unset, it will take the the global git config's value (github.user). If that is not 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.
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 take the value of of the global git config's value if it is left unset.
dir::AbstractString=~/.julia/dev: Directory in which the package will go. Relative paths are converted to absolute ones at template creation time.
julia_version::VersionNumber=1.0.0: Minimum allowed Julia version.
ssh::Bool=false: Whether or not to use SSH for the git remote. If false HTTPS will be used.
dev::Bool=true: Whether or not to Pkg.develop generated packages.
manifest::Bool=false: Whether or not to commit the Manifest.toml.
plugins::Vector{<:Plugin}=Plugin[]: A list of Plugins that the package will include.
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::Union{AbstractString, Nothing}: 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
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::Union{AbstractString, Nothing}: 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
struct MyPlugin <: GenericPlugin
gitignore::Vector{AbstractString}
src::Union{AbstractString, Nothing}
dest::AbstractString
@@ -34,7 +34,7 @@
end
end
-interactive(::Type{MyPlugin}) = interactive(MyPlugin; 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}} => year(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, as long as they conform to the usual type signature.
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}} => year(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, as long as they conform to the usual type signature.
Attributes
gitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.
Example
struct MyPlugin <: CustomPlugin
gitignore::Vector{AbstractString}
lucky::Bool
@@ -66,9 +66,9 @@ interactive(::Type{MyPlugin}) = interactive(MyPlugin; file="my-plugin.toml&
end
end
-interactive(: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.
Interactively create a plugin of type T, 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.
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.
Interactively create a plugin of type T, 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.
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 behind PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development.
Add CirrusCI to a template's plugins to add a .cirrus.yml configuration file to generated repositories, and an appropriate badge to the README. The default configuration file supports only FreeBSD builds via CirrusCI.jl
Keyword Arguments
config_file::Union{AbstractString, Nothing}="": Path to a custom .cirrus.yml. If nothing is supplied, no file will be generated.
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, Nothing}=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, Nothing}=nothing: Path to a custom .coveralls.yml. If left unset, no file will be generated.
Add a Documenter subtype to a template's plugins to add support for documentation generation via Documenter.jl.
By default, the plugin generates a minimal index.md and a make.jl file. The make.jl file contains the Documenter.makedocs command with predefined values for modules, format, pages, repo, sitename, and authors.
The subtype is expected to include the following fields:
assets::Vector{AbstractString}, a list of filenames to be included as the assets
kwarg to makedocs
gitignore::Vector{AbstractString}, a list of files to be added to the .gitignore
It may optionally include the field additional_kwargs::Union{AbstractDict, NamedTuple} to allow additional kwargs to be added to makedocs.
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.
Note
If deploying documentation with Travis CI, don't forget to complete the required configuration (see here).
Add GitLabPages to a template's plugins to add Documenter support via GitLab Pages, including automatic uploading of documentation from GitLabCI. 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 behind PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development.
Add CirrusCI to a template's plugins to add a .cirrus.yml configuration file to generated repositories, and an appropriate badge to the README. The default configuration file supports only FreeBSD builds via CirrusCI.jl
Keyword Arguments
config_file::Union{AbstractString, Nothing}="": Path to a custom .cirrus.yml. If nothing is supplied, no file will be generated.
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, Nothing}=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, Nothing}=nothing: Path to a custom .coveralls.yml. If left unset, no file will be generated.
Add a Documenter subtype to a template's plugins to add support for documentation generation via Documenter.jl.
By default, the plugin generates a minimal index.md and a make.jl file. The make.jl file contains the Documenter.makedocs command with predefined values for modules, format, pages, repo, sitename, and authors.
The subtype is expected to include the following fields:
assets::Vector{AbstractString}, a list of filenames to be included as the assets
kwarg to makedocs
gitignore::Vector{AbstractString}, a list of files to be added to the .gitignore
It may optionally include the field additional_kwargs::Union{AbstractDict, NamedTuple} to allow additional kwargs to be added to makedocs.
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.
Note
If deploying documentation with Travis CI, don't forget to complete the required configuration (see here).
Add GitLabPages to a template's plugins to add Documenter support via GitLab Pages, including automatic uploading of documentation from GitLabCI. 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.