diff --git a/latest/index.html b/latest/index.html index 1756e42..60c5146 100644 --- a/latest/index.html +++ b/latest/index.html @@ -1,11 +1,11 @@ -Home · PkgTemplates.jl
Home

PkgTemplates

Stable Latest Build Status Build Status CodeCov

PkgTemplates is a Julia package for creating new Julia packages in an easy, repeatable, and customizable way.

Installation

PkgTemplates is registered in METADATA.jl, so run Pkg.add("PkgTemplates") for the latest release, or Pkg.clone("PkgTemplates") for the development version.

Usage

The simplest template only requires your GitHub username.

julia> using PkgTemplates
+Home · PkgTemplates.jl
Home
PkgTemplates
Stable Latest Build Status Build Status CodeCov
PkgTemplates is a Julia package for creating new Julia packages in an easy, repeatable, and customizable way.
Installation
PkgTemplates is registered in METADATA.jl, so run Pkg.add("PkgTemplates") for the latest release, or Pkg.clone("PkgTemplates") for the development version.
Usage
The simplest template only requires your GitHub username.
julia> using PkgTemplates
 
 julia> t = Template(; user="myusername")
 PkgTemplates.Template("myusername", "github.com", "MIT", "Travis CI User", "2017", "/home/travis/.julia/v0.6", v"0.6.0", AbstractString[], Dict{Any,Any}(), Dict{DataType,PkgTemplates.Plugin}())
 
 julia> generate("MyPkg", t)
-INFO: Initialized git repo at /tmp/tmpOPxete/MyPkg
+INFO: Initialized git repo at /tmp/tmpxDMyLD/MyPkg
 INFO: Made initial empty commit
 INFO: Set remote origin to https://github.com/myusername/MyPkg.jl
 INFO: Staged 6 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE
@@ -38,15 +38,15 @@ julia> t = Template(;
                GitHubPages(),
            ],
        )
-PkgTemplates.Template("myusername", "github.com", "MIT", "Chris de Graaf, Invenia Technical Computing Corporation", "2016-2017", "/home/travis/code", v"0.5.2", AbstractString["PkgTemplates"], Dict("diff.renames"=>true), Dict{DataType,PkgTemplates.Plugin}(Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.GitHubPages, PkgTemplates.GitHubPages(AbstractString["/docs/build/", "/docs/site/"], AbstractString[])),Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.AppVeyor, PkgTemplates.AppVeyor(AbstractString[], "/home/travis/.julia/v0.6/PkgTemplates/defaults/appveyor.yml", ".appveyor.yml", PkgTemplates.Badge[PkgTemplates.Badge("Build Status", "https://ci.appveyor.com/api/projects/status/github/{{USER}}/{{PKGNAME}}.jl?svg=true", "https://ci.appveyor.com/project/{{USER}}/{{PKGNAME}}-jl")], Dict{String,Any}())),Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.Coveralls, PkgTemplates.Coveralls(AbstractString["*.jl.cov", "*.jl.*.cov", "*.jl.mem"], #NULL, ".coveralls.yml", PkgTemplates.Badge[PkgTemplates.Badge("Coveralls", "https://coveralls.io/repos/github/{{USER}}/{{PKGNAME}}.jl/badge.svg?branch=master", "https://coveralls.io/github/{{USER}}/{{PKGNAME}}.jl?branch=master")], Dict{String,Any}())),Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.CodeCov, PkgTemplates.CodeCov(AbstractString["*.jl.cov", "*.jl.*.cov", "*.jl.mem"], #NULL, ".codecov.yml", PkgTemplates.Badge[PkgTemplates.Badge("CodeCov", "https://codecov.io/gh/{{USER}}/{{PKGNAME}}.jl/branch/master/graph/badge.svg", "https://codecov.io/gh/{{USER}}/{{PKGNAME}}.jl")], Dict{String,Any}())),Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.TravisCI, PkgTemplates.TravisCI(AbstractString[], "/home/travis/.julia/v0.6/PkgTemplates/defaults/travis.yml", ".travis.yml", PkgTemplates.Badge[PkgTemplates.Badge("Build Status", "https://travis-ci.org/{{USER}}/{{PKGNAME}}.jl.svg?branch=master", "https://travis-ci.org/{{USER}}/{{PKGNAME}}.jl")], Dict{String,Any}()))))
+PkgTemplates.Template("myusername", "github.com", "MIT", "Chris de Graaf, Invenia Technical Computing Corporation", "2016-2017", "/home/travis/code", v"0.5.2", AbstractString["PkgTemplates"], Dict("diff.renames"=>true), Dict{DataType,PkgTemplates.Plugin}(Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.TravisCI, PkgTemplates.TravisCI(AbstractString[], "/home/travis/.julia/v0.6/PkgTemplates/defaults/travis.yml", ".travis.yml", PkgTemplates.Badge[PkgTemplates.Badge("Build Status", "https://travis-ci.org/{{USER}}/{{PKGNAME}}.jl.svg?branch=master", "https://travis-ci.org/{{USER}}/{{PKGNAME}}.jl")], Dict{String,Any}())),Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.AppVeyor, PkgTemplates.AppVeyor(AbstractString[], "/home/travis/.julia/v0.6/PkgTemplates/defaults/appveyor.yml", ".appveyor.yml", PkgTemplates.Badge[PkgTemplates.Badge("Build Status", "https://ci.appveyor.com/api/projects/status/github/{{USER}}/{{PKGNAME}}.jl?svg=true", "https://ci.appveyor.com/project/{{USER}}/{{PKGNAME}}-jl")], Dict{String,Any}())),Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.GitHubPages, PkgTemplates.GitHubPages(AbstractString["/docs/build/", "/docs/site/"], AbstractString[])),Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.CodeCov, PkgTemplates.CodeCov(AbstractString["*.jl.cov", "*.jl.*.cov", "*.jl.mem"], #NULL, ".codecov.yml", PkgTemplates.Badge[PkgTemplates.Badge("CodeCov", "https://codecov.io/gh/{{USER}}/{{PKGNAME}}.jl/branch/master/graph/badge.svg", "https://codecov.io/gh/{{USER}}/{{PKGNAME}}.jl")], Dict{String,Any}())),Pair{DataType,PkgTemplates.Plugin}(PkgTemplates.Coveralls, PkgTemplates.Coveralls(AbstractString["*.jl.cov", "*.jl.*.cov", "*.jl.mem"], #NULL, ".coveralls.yml", PkgTemplates.Badge[PkgTemplates.Badge("Coveralls", "https://coveralls.io/repos/github/{{USER}}/{{PKGNAME}}.jl/badge.svg?branch=master", "https://coveralls.io/github/{{USER}}/{{PKGNAME}}.jl?branch=master")], Dict{String,Any}()))))
 
 julia> generate("MyPkg", t; force=true, ssh=true)
-INFO: Initialized git repo at /tmp/tmpu5lmrg/MyPkg
+INFO: Initialized git repo at /tmp/tmpA25O86/MyPkg
 INFO: Applying git configuration
 INFO: Made initial empty commit
 INFO: Set remote origin to git@github.com:myusername/MyPkg.jl.git
 INFO: Created empty gh-pages branch
-INFO: Staged 9 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE, docs/, .appveyor.yml, .travis.yml
+INFO: Staged 9 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE, .travis.yml, .appveyor.yml, docs/
 INFO: Committed files generated by PkgTemplates
 INFO: Moving temporary package directory into /home/travis/code/
 INFO: Finished
@@ -62,4 +62,4 @@ REQUIRE
 docs/make.jl
 docs/src/index.md
 src/MyPkg.jl
-test/runtests.jl
If that looks like a lot of work, you can also create templates interactively with interactive_template:
asciicast
And if that's still too much work for you, you can call interactive_template with fast=true to use default values for everything but username and plugin selection.
Comparison to PkgDev
PkgTemplates is similar in functionality to PkgDev's generate function. However, PkgTemplates offers more customizability in templates and more extensibility via plugins. For the package registration and release management features that PkgTemplates lacks, you are encouraged to use AttoBot instead.

+test/runtests.jl

If that looks like a lot of work, you can also create templates interactively with interactive_template:

asciicast

And if that's still too much work for you, you can call interactive_template with fast=true to use default values for everything but username and plugin selection.

You can also use generate_interactive to interactively generate a template and then immediately use it to create a new package.

Comparison to PkgDev

PkgTemplates is similar in functionality to PkgDev's generate function. However, PkgTemplates offers more customizability in templates and more extensibility via plugins. For the package registration and release management features that PkgTemplates lacks, you are encouraged to use AttoBot instead.

diff --git a/latest/pages/index.html b/latest/pages/index.html index 309e0de..ef10f1f 100644 --- a/latest/pages/index.html +++ b/latest/pages/index.html @@ -1,2 +1,2 @@ -Index · PkgTemplates.jl
Index

Index

+Index · PkgTemplates.jl
Index

Index

diff --git a/latest/pages/licenses.html b/latest/pages/licenses.html index 8985db2..7dec865 100644 --- a/latest/pages/licenses.html +++ b/latest/pages/licenses.html @@ -1,2 +1,2 @@ -Licenses · PkgTemplates.jl
Licenses

Licenses

Many open-source licenses are available for use with PkgTemplates, but if you see that one is missing, don't hesitate to open an issue or PR.

available_licenses

PkgTemplates.available_licenses — Function.
available_licenses([io::IO]) -> Void

Print the names of all available licenses.

source

show_license

PkgTemplates.show_license — Function.
show_license([io::IO], license::AbstractString) -> Void

Print the text of license.

source

Helper Functions

read_license

PkgTemplates.read_license — Function.
read_license(license::AbstractString) -> String

Returns the contents of license. Errors if it is not found. Use available_licenses to view available licenses.

source
+Licenses · PkgTemplates.jl
Licenses

Licenses

Many open-source licenses are available for use with PkgTemplates, but if you see that one is missing, don't hesitate to open an issue or PR.

available_licenses

PkgTemplates.available_licenses — Function.
available_licenses([io::IO]) -> Void

Print the names of all available licenses.

source

show_license

PkgTemplates.show_license — Function.
show_license([io::IO], license::AbstractString) -> Void

Print the text of license.

source

Helper Functions

read_license

PkgTemplates.read_license — Function.
read_license(license::AbstractString) -> String

Returns the contents of license. Errors if it is not found. Use available_licenses to view available licenses.

source
diff --git a/latest/pages/package_generation.html b/latest/pages/package_generation.html index 8fe78da..88477fe 100644 --- a/latest/pages/package_generation.html +++ b/latest/pages/package_generation.html @@ -1,37 +1,37 @@ -Package Generation · PkgTemplates.jl
Package Generation

Package Generation

Creating new packages with PkgTemplates revolves around creating a new Template, then calling generate on it.

Template

PkgTemplates.Template — Type.
Template(; kwargs...) -> 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.

  • 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.

  • gitconfig::Dict=Dict(): Git configuration options.

  • plugins::Vector{<:Plugin}=Plugin[]: A list of Plugins that the package will include.

source
PkgTemplates.interactive_template — Function.
interactive_template(; fast::Bool=false) -> Template

Interactively create a Template. If fast is set, defaults will be assumed for all values except username and plugins.

source

generate

PkgTemplates.generate — Function.
generate(
+Package Generation · PkgTemplates.jl
Package Generation
Package Generation
Creating new packages with PkgTemplates revolves around creating a new Template, then calling generate on it.
Template
PkgTemplates.Template — Type.
Template(; kwargs...) -> 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.
  • 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.
  • gitconfig::Dict=Dict(): Git configuration options.
  • plugins::Vector{<:Plugin}=Plugin[]: A list of Plugins that the package will include.
source
PkgTemplates.interactive_template — Function.
interactive_template(; fast::Bool=false) -> Template
Interactively create a Template. If fast is set, defaults will be assumed for all values except username and plugins.
source
generate
PkgTemplates.generate — Function.
generate(
     pkg_name::AbstractString,
     t::Template;
     force::Bool=false,
     ssh::Bool=false,
-) -> Void
Generate a package named pkg_name from template.
Keyword Arguments
  • 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.
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).
source
PkgTemplates.generate_interactive — Function.
generate_interactive(
+) -> Void
Generate a package named pkg_name from template.
Keyword Arguments
  • 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.
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).
source
PkgTemplates.generate_interactive — Function.
generate_interactive(
     pkg_name::AbstractString;
     force::Bool=false,
     ssh::Bool=false,
     backup_dir::AbstractString="",
     fast::Bool=false,
-) -> Void
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.
source
Helper Functions
gen_entrypoint
PkgTemplates.gen_entrypoint — Function.
gen_entrypoint(
+) -> Void
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.
source
Helper Functions
gen_entrypoint
PkgTemplates.gen_entrypoint — Function.
gen_entrypoint(
     dir::AbstractString,
     pkg_name::AbstractString,
     template::Template,
-) -> Vector{String}
Create the module entrypoint in the temp package directory.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose entrypoint we are generating.
Returns an array of generated file/directory names.
source
gen_tests
PkgTemplates.gen_tests — Function.
gen_tests(
+) -> Vector{String}
Create the module entrypoint in the temp package directory.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose entrypoint we are generating.
Returns an array of generated file/directory names.
source
gen_tests
PkgTemplates.gen_tests — Function.
gen_tests(
     dir::AbstractString,
     pkg_name::AbstractString,
     template::Template,
-) -> Vector{String}
Create the test directory and entrypoint in the temp package directory.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose tests we are generating.
Returns an array of generated file/directory names.
source
gen_require
PkgTemplates.gen_require — Function.
gen_require(
+) -> Vector{String}
Create the test directory and entrypoint in the temp package directory.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose tests we are generating.
Returns an array of generated file/directory names.
source
gen_require
PkgTemplates.gen_require — Function.
gen_require(
     dir::AbstractString,
     pkg_name::AbstractString,
     template::Template,
-) -> Vector{String}
Create the REQUIRE file in the temp package directory.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose REQUIRE we are generating.
Returns an array of generated file/directory names.
source
gen_readme
PkgTemplates.gen_readme — Function.
gen_readme(
+) -> Vector{String}
Create the REQUIRE file in the temp package directory.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose REQUIRE we are generating.
Returns an array of generated file/directory names.
source
gen_readme
PkgTemplates.gen_readme — Function.
gen_readme(
     dir::AbstractString,
     pkg_name::AbstractString,
     template::Template,
-) -> Vector{String}
Create a README in the temp package directory with badges for each enabled plugin.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose README we are generating.
Returns an array of generated file/directory names.
source
gen_gitignore
PkgTemplates.gen_gitignore — Function.
gen_gitignore(
+) -> Vector{String}
Create a README in the temp package directory with badges for each enabled plugin.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose README we are generating.
Returns an array of generated file/directory names.
source
gen_gitignore
PkgTemplates.gen_gitignore — Function.
gen_gitignore(
     dir::AbstractString,
     pkg_name::AbstractString,
     template::Template,
-) -> Vector{String}
Create a .gitignore in the temp package directory.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose .gitignore we are generating.
Returns an array of generated file/directory names.
source
gen_license
PkgTemplates.gen_license — Function.
gen_license(
+) -> Vector{String}
Create a .gitignore in the temp package directory.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose .gitignore we are generating.
Returns an array of generated file/directory names.
source
gen_license
PkgTemplates.gen_license — Function.
gen_license(
     dir::AbstractString,
     pkg_name::AbstractString,
     template::Template,
-) -> Vector{String}
Create a license in the temp package directory.
Arguments
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
  • template::Template: The template whose LICENSE we are generating.
Returns an array of generated file/directory names.
source

+) -> Vector{String}

Create a license in the temp package directory.

Arguments

  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.

  • pkg_name::AbstractString: Name of the package.

  • template::Template: The template whose LICENSE we are generating.

Returns an array of generated file/directory names.

source
diff --git a/latest/pages/plugin_development.html b/latest/pages/plugin_development.html index dbc0cf9..2e2f19a 100644 --- a/latest/pages/plugin_development.html +++ b/latest/pages/plugin_development.html @@ -1,5 +1,5 @@ -Plugin Development · PkgTemplates.jl
Plugin Development

Plugin Development

The best and easiest way to contribute to PkgTemplates is to write new plugins.

There are two types of plugins: GenericPlugins and CustomPlugins.

Generic Plugins

PkgTemplates.GenericPlugin — Type.

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
Plugin Development
Plugin Development
The best and easiest way to contribute to PkgTemplates is to write new plugins.
There are two types of plugins: GenericPlugins and CustomPlugins.
Generic Plugins
PkgTemplates.GenericPlugin — Type.
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
@@ -32,7 +32,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.
source
Custom Plugins
PkgTemplates.CustomPlugin — Type.
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
+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.
source
Custom Plugins
PkgTemplates.CustomPlugin — Type.
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
 
@@ -74,16 +74,16 @@ interactive(plugin_type::Type{MyPlugin}) = interactive(plugin_type; file="m
     end
 end
 
-interactive(plugin_type::Type{MyPlugin}) = MyPlugin()
This plugin doesn't do much, but it demonstrates how gen_plugin, badges and interactive can be implemented using substitute, gen_file, Badge, and format.
Defining Template Files
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).
source
CustomPlugin Required Methods
gen_plugin
PkgTemplates.gen_plugin — Function.
gen_plugin(
+interactive(plugin_type::Type{MyPlugin}) = MyPlugin()
This plugin doesn't do much, but it demonstrates how gen_plugin, badges and interactive can be implemented using substitute, gen_file, Badge, and format.
Defining Template Files
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).
source
CustomPlugin Required Methods
gen_plugin
PkgTemplates.gen_plugin — Function.
gen_plugin(
     plugin::Plugin,
     template::Template,
     dir::AbstractString,
     pkg_name::AbstractString
-) -> Vector{String}
Generate any files associated with a plugin.
Arguments
  • plugin::Plugin: Plugin whose files are being generated.
  • template::Template: Template configuration.
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
Returns an array of generated file/directory names.
source
PkgTemplates.interactive — Function.
interactive(
+) -> Vector{String}
Generate any files associated with a plugin.
Arguments
  • plugin::Plugin: Plugin whose files are being generated.
  • template::Template: Template configuration.
  • dir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.
  • pkg_name::AbstractString: Name of the package.
Returns an array of generated file/directory names.
source
PkgTemplates.interactive — Function.
interactive(
     plugin_type::Type{P <: Plugin};
     file::Union{AbstractString, Void}="",
-) -> Plugin
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").
source
Note: interactive is not strictly required, however without it, your custom plugin will not be available when creating templates with interactive_template.
badges
PkgTemplates.badges — Function.
badges(plugin::Plugin, user::AbstractString, pkg_name::AbstractString) -> Vector{String}
Generate Markdown badges for the plugin.
Arguments
  • plugin::Plugin: Plugin whose badges we are generating.
  • user::AbstractString: Username of the package creator.
  • pkg_name::AbstractString: Name of the package.
Returns an array of Markdown badges.
source
Helper Types/Functions
gen_file
PkgTemplates.gen_file — Function.
gen_file(file_path::AbstractString, text::AbstractString) -> Int
Create a new file containing some given text. Always ends the file with a newline.
Arguments
  • file::AbstractString: Path to the file to be created.
  • text::AbstractString: Text to write to the file.
Returns the number of bytes written to the file.
source
substitute
PkgTemplates.substitute — Function.
substitute(template::AbstractString, view::Dict{String, Any}) -> String
Replace placeholders in template with values in view via Mustache. template is not modified.
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.
source
substitute(
+) -> Plugin
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").
source
Note: interactive is not strictly required, however without it, your custom plugin will not be available when creating templates with interactive_template.
badges
PkgTemplates.badges — Function.
badges(plugin::Plugin, user::AbstractString, pkg_name::AbstractString) -> Vector{String}
Generate Markdown badges for the plugin.
Arguments
  • plugin::Plugin: Plugin whose badges we are generating.
  • user::AbstractString: Username of the package creator.
  • pkg_name::AbstractString: Name of the package.
Returns an array of Markdown badges.
source
Helper Types/Functions
gen_file
PkgTemplates.gen_file — Function.
gen_file(file_path::AbstractString, text::AbstractString) -> Int
Create a new file containing some given text. Always ends the file with a newline.
Arguments
  • file::AbstractString: Path to the file to be created.
  • text::AbstractString: Text to write to the file.
Returns the number of bytes written to the file.
source
substitute
PkgTemplates.substitute — Function.
substitute(template::AbstractString, view::Dict{String, Any}) -> String
Replace placeholders in template with values in view via Mustache. template is not modified.
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.
source
substitute(
     template::AbstractString,
     pkg_template::Template;
     view::Dict{String, Any}=Dict{String, Any}(),
-) -> String
Replace placeholders in template, using some default replacements based on the pkg_template and additional ones in view. template is not modified.
source
Badge
PkgTemplates.Badge — Type.
Badge(hover::AbstractString, image::AbstractString, link::AbstractString) -> Badge
A Badge contains the data necessary to generate a Markdown badge.
Arguments
  • hover::AbstractString: Text to appear when the mouse is hovered over the badge.
  • image::AbstractString: URL to the image to display.
  • link::AbstractString: URL to go to upon clicking the badge.
source
format
PkgTemplates.format — Function.
format(b::Badge)
Return badge's data formatted as a Markdown string.
source
version_floor
PkgTemplates.version_floor — Function.
version_floor(v::VersionNumber=VERSION) -> String
Format the given Julia version.
Keyword arguments
  • v::VersionNumber=VERSION: Version to floor.
Returns "major.minor" for the most recent release version relative to v. For prereleases with v.minor == v.patch == 0, returns "major.minor-".
source

+) -> String

Replace placeholders in template, using some default replacements based on the pkg_template and additional ones in view. template is not modified.

source

Badge

PkgTemplates.Badge — Type.
Badge(hover::AbstractString, image::AbstractString, link::AbstractString) -> Badge

A Badge contains the data necessary to generate a Markdown badge.

Arguments

  • hover::AbstractString: Text to appear when the mouse is hovered over the badge.

  • image::AbstractString: URL to the image to display.

  • link::AbstractString: URL to go to upon clicking the badge.

source

format

PkgTemplates.format — Function.
format(b::Badge)

Return badge's data formatted as a Markdown string.

source

version_floor

PkgTemplates.version_floor — Function.
version_floor(v::VersionNumber=VERSION) -> String

Format the given Julia version.

Keyword arguments

  • v::VersionNumber=VERSION: Version to floor.

Returns "major.minor" for the most recent release version relative to v. For prereleases with v.minor == v.patch == 0, returns "major.minor-".

source
diff --git a/latest/pages/plugins.html b/latest/pages/plugins.html index b44e4a7..c0b8500 100644 --- a/latest/pages/plugins.html +++ b/latest/pages/plugins.html @@ -1,2 +1,2 @@ -Plugins · PkgTemplates.jl
Plugins

Plugins

Plugins are the driver for PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development.

TravisCI

PkgTemplates.TravisCI — Type.
TravisCI(; config_file::Union{AbstractString, Void}="") -> TravisCI

Add TravisCI to a template's plugins to add a .travis.yml configuration file to generated repositories, and an appropriate badge to the README.

Keyword Arguments:

  • config_file::Union{AbstractString, Void}="": Path to a custom .travis.yml. If nothing is supplied, no file will be generated.

source

AppVeyor

PkgTemplates.AppVeyor — Type.
AppVeyor(; config_file::Union{AbstractString, Void}="") -> AppVeyor

Add AppVeyor to a template's plugins to add a .appveyor.yml configuration file to generated repositories, and an appropriate badge to the README.

Keyword Arguments

  • config_file::Union{AbstractString, Void}="": Path to a custom .appveyor.yml. If nothing is supplied, no file will be generated.

source

GitLabCI

PkgTemplates.GitLabCI — Type.
GitLabCI(; config_file::Union{AbstractString, Void}="", coverage::Bool=true) -> GitLabCI

Add GitLabCI to a template's plugins to add a .gitlab-ci.yml configuration file to generated repositories, and appropriate badge(s) to the README.

Keyword Arguments:

  • config_file::Union{AbstractString, Void}="": Path to a custom .gitlab-ci.yml. If nothing is supplied, no file will be generated.

  • coverage::Bool=true: Whether or not GitLab CI's built-in code coverage analysis should be enabled. If enabled, you must set a regex in your repo settings; use Test Coverage (d+.d+)%.

source

CodeCov

PkgTemplates.CodeCov — Type.
CodeCov(; config_file::Union{AbstractString, Void}="") -> CodeCov

Add CodeCov to a template's plugins to 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}="": Path to a custom .codecov.yml. If nothing is supplied, no file will be generated.

source

Coveralls

PkgTemplates.Coveralls — Type.
Coveralls(; config_file::Union{AbstractString, Void}="") -> Coveralls

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.

source

Documenter

PkgTemplates.Documenter — Type.

Add a Documenter subtype to a template's plugins to add support for documentation generation via Documenter.jl.

source

GitHubPages

PkgTemplates.GitHubPages — Type.
GitHubPages(; assets::Vector{<:AbstractString}=String[]) -> GitHubPages

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{String}=String[]: Array of paths to Documenter asset files.

source
+Plugins · PkgTemplates.jl
Plugins

Plugins

Plugins are the driver for PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development.

TravisCI

PkgTemplates.TravisCI — Type.
TravisCI(; config_file::Union{AbstractString, Void}="") -> TravisCI

Add TravisCI to a template's plugins to add a .travis.yml configuration file to generated repositories, and an appropriate badge to the README.

Keyword Arguments:

  • config_file::Union{AbstractString, Void}="": Path to a custom .travis.yml. If nothing is supplied, no file will be generated.

source

AppVeyor

PkgTemplates.AppVeyor — Type.
AppVeyor(; config_file::Union{AbstractString, Void}="") -> AppVeyor

Add AppVeyor to a template's plugins to add a .appveyor.yml configuration file to generated repositories, and an appropriate badge to the README.

Keyword Arguments

  • config_file::Union{AbstractString, Void}="": Path to a custom .appveyor.yml. If nothing is supplied, no file will be generated.

source

GitLabCI

PkgTemplates.GitLabCI — Type.
GitLabCI(; config_file::Union{AbstractString, Void}="", coverage::Bool=true) -> GitLabCI

Add GitLabCI to a template's plugins to add a .gitlab-ci.yml configuration file to generated repositories, and appropriate badge(s) to the README.

Keyword Arguments:

  • config_file::Union{AbstractString, Void}="": Path to a custom .gitlab-ci.yml. If nothing is supplied, no file will be generated.

  • coverage::Bool=true: Whether or not GitLab CI's built-in code coverage analysis should be enabled. If enabled, you must set a regex in your repo settings; use Test Coverage (d+.d+)%.

source

CodeCov

PkgTemplates.CodeCov — Type.
CodeCov(; config_file::Union{AbstractString, Void}="") -> CodeCov

Add CodeCov to a template's plugins to 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}="": Path to a custom .codecov.yml. If nothing is supplied, no file will be generated.

source

Coveralls

PkgTemplates.Coveralls — Type.
Coveralls(; config_file::Union{AbstractString, Void}="") -> Coveralls

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.

source

Documenter

PkgTemplates.Documenter — Type.

Add a Documenter subtype to a template's plugins to add support for documentation generation via Documenter.jl.

source

GitHubPages

PkgTemplates.GitHubPages — Type.
GitHubPages(; assets::Vector{<:AbstractString}=String[]) -> GitHubPages

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{String}=String[]: Array of paths to Documenter asset files.

source
diff --git a/latest/search_index.js b/latest/search_index.js index cbf8fc5..0c024fc 100644 --- a/latest/search_index.js +++ b/latest/search_index.js @@ -29,7 +29,7 @@ var documenterSearchIndex = {"docs": [ "page": "Home", "title": "Usage", "category": "section", - "text": "The simplest template only requires your GitHub username.using PkgTemplates\nt = Template(; user=\"myusername\")\ngenerate(\"MyPkg\", t)\ncd(joinpath(t.dir, \"MyPkg\")); run(`git ls-tree -r --name-only HEAD`)However, we can also configure a number of keyword arguments to Template and generate:using PkgTemplates\nt = Template(;\n user=\"myusername\",\n license=\"MIT\",\n authors=[\"Chris de Graaf\", \"Invenia Technical Computing Corporation\"],\n years=\"2016-2017\",\n dir=joinpath(homedir(), \"code\"),\n julia_version=v\"0.5.2\",\n requirements=[\"PkgTemplates\"],\n gitconfig=Dict(\"diff.renames\" => true),\n plugins=[\n TravisCI(),\n CodeCov(; config_file=nothing),\n Coveralls(),\n AppVeyor(),\n GitHubPages(),\n ],\n)\ngenerate(\"MyPkg\", t; force=true, ssh=true)\ncd(joinpath(t.dir, \"MyPkg\")); run(`git ls-tree -r --name-only HEAD`)If that looks like a lot of work, you can also create templates interactively with interactive_template:(Image: asciicast)And if that's still too much work for you, you can call interactive_template with fast=true to use default values for everything but username and plugin selection." + "text": "The simplest template only requires your GitHub username.using PkgTemplates\nt = Template(; user=\"myusername\")\ngenerate(\"MyPkg\", t)\ncd(joinpath(t.dir, \"MyPkg\")); run(`git ls-tree -r --name-only HEAD`)However, we can also configure a number of keyword arguments to Template and generate:using PkgTemplates\nt = Template(;\n user=\"myusername\",\n license=\"MIT\",\n authors=[\"Chris de Graaf\", \"Invenia Technical Computing Corporation\"],\n years=\"2016-2017\",\n dir=joinpath(homedir(), \"code\"),\n julia_version=v\"0.5.2\",\n requirements=[\"PkgTemplates\"],\n gitconfig=Dict(\"diff.renames\" => true),\n plugins=[\n TravisCI(),\n CodeCov(; config_file=nothing),\n Coveralls(),\n AppVeyor(),\n GitHubPages(),\n ],\n)\ngenerate(\"MyPkg\", t; force=true, ssh=true)\ncd(joinpath(t.dir, \"MyPkg\")); run(`git ls-tree -r --name-only HEAD`)If that looks like a lot of work, you can also create templates interactively with interactive_template:(Image: asciicast)And if that's still too much work for you, you can call interactive_template with fast=true to use default values for everything but username and plugin selection.You can also use generate_interactive to interactively generate a template and then immediately use it to create a new package." }, {