From 5b1a22568bd5874a96014935ddf0ffb222501a0b Mon Sep 17 00:00:00 2001 From: zeptodoctor <44736852+zeptodoctor@users.noreply.github.com> Date: Sun, 29 Mar 2020 22:12:34 +0000 Subject: [PATCH] build based on b603011 --- dev/developer/index.html | 12 ++++++------ dev/index.html | 2 +- dev/migrating/index.html | 2 +- dev/search/index.html | 2 +- dev/user/index.html | 12 ++++++------ 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/dev/developer/index.html b/dev/developer/index.html index 7d96aa0..d1611ca 100644 --- a/dev/developer/index.html +++ b/dev/developer/index.html @@ -1,14 +1,14 @@ -Developer Guide · PkgTemplates.jl
Edit on GitHub

PkgTemplates Developer Guide

PkgTemplates can be easily extended by adding new Plugins.

There are two types of plugins: Plugin and BasicPlugin.

PkgTemplates.Plugin — Type

Plugins are PkgTemplates' source of customization and extensibility. Add plugins to your Templates to enable extra pieces of repository setup.

When implementing a new plugin, subtype this type to have full control over its behaviour.

source

Template + Package Creation Pipeline

The Template constructor basically does this:

- extract values from keyword arguments
+Developer Guide · PkgTemplates.jl
Edit on GitHub
PkgTemplates Developer Guide
PkgTemplates can be easily extended by adding new Plugins.
There are two types of plugins: Plugin and BasicPlugin.
PkgTemplates.Plugin — Type
Plugins are PkgTemplates' source of customization and extensibility. Add plugins to your Templates to enable extra pieces of repository setup.
When implementing a new plugin, subtype this type to have full control over its behaviour.
source
Template + Package Creation Pipeline
The Template constructor basically does this:
- extract values from keyword arguments
 - create a Template from the values
 - for each plugin:
-  - validate plugin against the template
The plugin validation step uses the validate function. It lets us catch mistakes before we try to generate packages.
PkgTemplates.validate — Function
validate(::Plugin, ::Template)
Perform any required validation for a Plugin.
It is preferred to do validation here instead of in prehook, because this function is called at Template construction time, whereas the prehook is only run at package generation time.
source
The package generation process looks like this:
- create empty directory for the package
+  - validate plugin against the template
The plugin validation step uses the validate function. It lets us catch mistakes before we try to generate packages.
PkgTemplates.validate — Function
validate(::Plugin, ::Template)
Perform any required validation for a Plugin.
It is preferred to do validation here instead of in prehook, because this function is called at Template construction time, whereas the prehook is only run at package generation time.
source
The package generation process looks like this:
- create empty directory for the package
 - for each plugin, ordered by priority:
   - run plugin prehook
 - for each plugin, ordered by priority:
   - run plugin hook
 - for each plugin, ordered by priority:
-  - run plugin posthook
As you can tell, plugins play a central role in setting up a package.
The three main entrypoints for plugins to do work are the prehook, the hook, and the posthook. As the names might imply, they basically mean "before the main stage", "the main stage", and "after the main stage", respectively.
Each stage is basically identical, since the functions take the exact same arguments. However, the multiple stages allow us to depend on artifacts of the previous stages. For example, the Git plugin uses posthook to commit all generated files, but it wouldn't make sense to do that before the files are generated.
But what about dependencies within the same stage? In this case, we have priority to define which plugins go when. The Git plugin also uses this function to lower its posthook's priority, so that even if other plugins generate files in their posthooks, they still get committed (provided that those plugins didn't set an even lower priority).
PkgTemplates.prehook — Function
prehook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 1 of the package generation process (the "before" stage, in general). At this point, pkg_dir is an empty directory that will eventually contain the package, and neither the hooks nor the posthooks have run.
Note
pkg_dir only stays empty until the first plugin chooses to create a file. See also: priority.
source
PkgTemplates.hook — Function
hook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 2 of the package generation pipeline (the "main" stage, in general). At this point, the prehooks have run, but not the posthooks.
pkg_dir is the directory in which the package is being generated (so basename(pkg_dir) is the package name).
Note
You usually shouldn't implement this function for BasicPlugins. If you do, it should probably invoke the generic method (otherwise, there's not much reason to subtype BasicPlugin).
source
PkgTemplates.posthook — Function
posthook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 3 of the package generation pipeline (the "after" stage, in general). At this point, both the prehooks and hooks have run.
source
PkgTemplates.priority — Function
priority(::Plugin, ::Union{typeof(prehook), typeof(hook), typeof(posthook)}) -> Int
Determines the order in which plugins are processed (higher goes first). The default priority (DEFAULT_PRIORITY), is 1000.
You can implement this function per-stage (by using ::typeof(hook), for example), or for all stages by simply using ::Function.
source
Plugin Walkthrough
Concrete types that subtype Plugin directly are free to do almost anything. To understand how they're implemented, let's look at simplified versions of two plugins: Documenter to explore templating, and Git to further clarify the multi-stage pipeline.
Example: Documenter
@with_kw_noshow struct Documenter <: Plugin
+  - run plugin posthook
As you can tell, plugins play a central role in setting up a package.
The three main entrypoints for plugins to do work are the prehook, the hook, and the posthook. As the names might imply, they basically mean "before the main stage", "the main stage", and "after the main stage", respectively.
Each stage is basically identical, since the functions take the exact same arguments. However, the multiple stages allow us to depend on artifacts of the previous stages. For example, the Git plugin uses posthook to commit all generated files, but it wouldn't make sense to do that before the files are generated.
But what about dependencies within the same stage? In this case, we have priority to define which plugins go when. The Git plugin also uses this function to lower its posthook's priority, so that even if other plugins generate files in their posthooks, they still get committed (provided that those plugins didn't set an even lower priority).
PkgTemplates.prehook — Function
prehook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 1 of the package generation process (the "before" stage, in general). At this point, pkg_dir is an empty directory that will eventually contain the package, and neither the hooks nor the posthooks have run.
Note
pkg_dir only stays empty until the first plugin chooses to create a file. See also: priority.
source
PkgTemplates.hook — Function
hook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 2 of the package generation pipeline (the "main" stage, in general). At this point, the prehooks have run, but not the posthooks.
pkg_dir is the directory in which the package is being generated (so basename(pkg_dir) is the package name).
Note
You usually shouldn't implement this function for BasicPlugins. If you do, it should probably invoke the generic method (otherwise, there's not much reason to subtype BasicPlugin).
source
PkgTemplates.posthook — Function
posthook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 3 of the package generation pipeline (the "after" stage, in general). At this point, both the prehooks and hooks have run.
source
PkgTemplates.priority — Function
priority(::Plugin, ::Union{typeof(prehook), typeof(hook), typeof(posthook)}) -> Int
Determines the order in which plugins are processed (higher goes first). The default priority (DEFAULT_PRIORITY), is 1000.
You can implement this function per-stage (by using ::typeof(hook), for example), or for all stages by simply using ::Function.
source
Plugin Walkthrough
Concrete types that subtype Plugin directly are free to do almost anything. To understand how they're implemented, let's look at simplified versions of two plugins: Documenter to explore templating, and Git to further clarify the multi-stage pipeline.
Example: Documenter
@with_kw_noshow struct Documenter <: Plugin
     make_jl::String = default_file("docs", "make.jl")
     index_md::String = default_file("docs", "src", "index.md")
 end
@@ -47,7 +47,7 @@ function hook(p::Documenter, t::Template, pkg_dir::AbstractString)
 
     # What this function does is not relevant here.
     create_documentation_project()
-end
The @with_kw_noshow macro defines keyword constructors for us. Inside of our struct definition, we're using default_file to refer to files in this repository.
PkgTemplates.default_file — Function
default_file(paths::AbstractString...) -> String
Return a path relative to the default template file directory (~/build/invenia/PkgTemplates.jl/templates).
source
The first method we implement for Documenter is gitignore, so that packages created with this plugin ignore documentation build artifacts.
PkgTemplates.gitignore — Function
gitignore(::Plugin) -> Vector{String}
Return patterns that should be added to .gitignore. These are used by the Git plugin.
By default, an empty list is returned.
source
Second, we implement badges to add a couple of badges to new packages' README files.
PkgTemplates.badges — Function
badges(::Plugin) -> Union{Badge, Vector{Badge}}
Return a list of Badges, or just one, to be added to README.md. These are used by the Readme plugin to add badges to the README.
By default, an empty list is returned.
source
PkgTemplates.Badge — Type
Badge(hover::AbstractString, image::AbstractString, link::AbstractString)
Container for Markdown badge data. Each argument can contain placeholders, which will be filled in with values from combined_view.
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
These two functions, gitignore and badges, are currently the only "special" functions for cross-plugin interactions. In other cases, you can still access the Template's plugins to depend on the presence/properties of other plugins, although that's less powerful.
Third, we implement view, which is used to fill placeholders in badges and rendered files.
PkgTemplates.view — Function
view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}
Return the view to be passed to the text templating engine for this plugin. pkg is the name of the package being generated.
For BasicPlugins, this is used for both the plugin badges (see badges) and the template file (see source). For other Plugins, it is used only for badges, but you can always call it yourself as part of your hook implementation.
By default, an empty Dict is returned.
source
Finally, we implement hook, which is the real workhorse for the plugin. Inside of this function, we generate a couple of files with the help of a few more text templating functions.
PkgTemplates.render_file — Function
render_file(file::AbstractString view::Dict{<:AbstractString}, tags) -> String
Render a template file with the data in view. tags should be a tuple of two strings, which are the opening and closing delimiters, or nothing to use the default delimiters.
source
PkgTemplates.render_text — Function
render_text(text::AbstractString, view::Dict{<:AbstractString}, tags=nothing) -> String
Render some text with the data in view. tags should be a tuple of two strings, which are the opening and closing delimiters, or nothing to use the default delimiters.
source
PkgTemplates.gen_file — Function
gen_file(file::AbstractString, text::AbstractString)
Create a new file containing some given text. Trailing whitespace is removed, and the file will end with a newline.
source
PkgTemplates.combined_view — Function
combined_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}
This function combines view and user_view for use in text templating. If you're doing manual file creation or text templating (i.e. writing Plugins that are not BasicPlugins), then you should use this function rather than either of the former two.
Note
Do not implement this function yourself! If you're implementing a plugin, you should implement view. If you're customizing a plugin as a user, you should implement user_view.
source
PkgTemplates.tags — Function
tags(::Plugin) -> Tuple{String, String}
Return the delimiters used for text templating. See the Citation plugin for a rare case where changing the tags is necessary.
By default, the tags are "{{" and "}}".
source
For more information on text templating, see the BasicPlugin Walkthrough and the section on Custom Template Files.
Example: Git
struct Git <: Plugin end
+end
The @with_kw_noshow macro defines keyword constructors for us. Inside of our struct definition, we're using default_file to refer to files in this repository.
PkgTemplates.default_file — Function
default_file(paths::AbstractString...) -> String
Return a path relative to the default template file directory (~/build/invenia/PkgTemplates.jl/templates).
source
The first method we implement for Documenter is gitignore, so that packages created with this plugin ignore documentation build artifacts.
PkgTemplates.gitignore — Function
gitignore(::Plugin) -> Vector{String}
Return patterns that should be added to .gitignore. These are used by the Git plugin.
By default, an empty list is returned.
source
Second, we implement badges to add a couple of badges to new packages' README files.
PkgTemplates.badges — Function
badges(::Plugin) -> Union{Badge, Vector{Badge}}
Return a list of Badges, or just one, to be added to README.md. These are used by the Readme plugin to add badges to the README.
By default, an empty list is returned.
source
PkgTemplates.Badge — Type
Badge(hover::AbstractString, image::AbstractString, link::AbstractString)
Container for Markdown badge data. Each argument can contain placeholders, which will be filled in with values from combined_view.
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
These two functions, gitignore and badges, are currently the only "special" functions for cross-plugin interactions. In other cases, you can still access the Template's plugins to depend on the presence/properties of other plugins, although that's less powerful.
Third, we implement view, which is used to fill placeholders in badges and rendered files.
PkgTemplates.view — Function
view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}
Return the view to be passed to the text templating engine for this plugin. pkg is the name of the package being generated.
For BasicPlugins, this is used for both the plugin badges (see badges) and the template file (see source). For other Plugins, it is used only for badges, but you can always call it yourself as part of your hook implementation.
By default, an empty Dict is returned.
source
Finally, we implement hook, which is the real workhorse for the plugin. Inside of this function, we generate a couple of files with the help of a few more text templating functions.
PkgTemplates.render_file — Function
render_file(file::AbstractString view::Dict{<:AbstractString}, tags) -> String
Render a template file with the data in view. tags should be a tuple of two strings, which are the opening and closing delimiters, or nothing to use the default delimiters.
source
PkgTemplates.render_text — Function
render_text(text::AbstractString, view::Dict{<:AbstractString}, tags=nothing) -> String
Render some text with the data in view. tags should be a tuple of two strings, which are the opening and closing delimiters, or nothing to use the default delimiters.
source
PkgTemplates.gen_file — Function
gen_file(file::AbstractString, text::AbstractString)
Create a new file containing some given text. Trailing whitespace is removed, and the file will end with a newline.
source
PkgTemplates.combined_view — Function
combined_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}
This function combines view and user_view for use in text templating. If you're doing manual file creation or text templating (i.e. writing Plugins that are not BasicPlugins), then you should use this function rather than either of the former two.
Note
Do not implement this function yourself! If you're implementing a plugin, you should implement view. If you're customizing a plugin as a user, you should implement user_view.
source
PkgTemplates.tags — Function
tags(::Plugin) -> Tuple{String, String}
Return the delimiters used for text templating. See the Citation plugin for a rare case where changing the tags is necessary.
By default, the tags are "{{" and "}}".
source
For more information on text templating, see the BasicPlugin Walkthrough and the section on Custom Template Files.
Example: Git
struct Git <: Plugin end
 
 priority(::Git, ::typeof(posthook)) = 5
 
@@ -94,7 +94,7 @@ view(::Citation, t::Template, pkg::AbstractString) = Dict(
     "PKG" => pkg,
     "URL" => "https://$(t.host)/$(t.user)/$pkg.jl",
     "YEAR" => year(today()),
-)
Similar to the Documenter example above, we're defining a keyword constructor, and assigning a default template file from this repository. This plugin adds nothing to .gitignore, and it doesn't add any badges, so implementations for gitignore and badges are omitted.
First, we implement source and destination to define where the template file comes from, and where it goes. These functions are specific to BasicPlugins, and have no effect on regular Plugins by default.
PkgTemplates.source — Function
source(::BasicPlugin) -> Union{String, Nothing}
Return the path to a plugin's template file, or nothing to indicate no file.
By default, nothing is returned.
source
PkgTemplates.destination — Function
destination(::BasicPlugin) -> String
Return the destination, relative to the package root, of a plugin's configuration file.
This function must be implemented.
source
Next, we implement tags. We briefly saw this function earlier, but in this case it's necessary to change its behaviour from the default. To see why, it might help to see the template file in its entirety:
@misc{<<&PKG>>.jl,
+)
Similar to the Documenter example above, we're defining a keyword constructor, and assigning a default template file from this repository. This plugin adds nothing to .gitignore, and it doesn't add any badges, so implementations for gitignore and badges are omitted.
First, we implement source and destination to define where the template file comes from, and where it goes. These functions are specific to BasicPlugins, and have no effect on regular Plugins by default.
PkgTemplates.source — Function
source(::BasicPlugin) -> Union{String, Nothing}
Return the path to a plugin's template file, or nothing to indicate no file.
By default, nothing is returned.
source
PkgTemplates.destination — Function
destination(::BasicPlugin) -> String
Return the destination, relative to the package root, of a plugin's configuration file.
This function must be implemented.
source
Next, we implement tags. We briefly saw this function earlier, but in this case it's necessary to change its behaviour from the default. To see why, it might help to see the template file in its entirety:
@misc{<<&PKG>>.jl,
 	author  = {<<&AUTHORS>>},
 	title   = {<<&PKG>>.jl},
 	url     = {<<&URL>>},
@@ -124,4 +124,4 @@ function hook(p::Tests, t::Template, pkg_dir::AbstractString)
     invoke(hook, Tuple{BasicPlugin, Template, AbstractString}, p, t, pkg_dir)
     # Do some other work.
     add_test_dependency()
-end
There is also a default validate implementation for BasicPlugins, which checks that the plugin's source file exists, and throws an ArgumentError otherwise. If you want to extend the validation but keep the file existence check, use the invoke method as described above.
For more examples, see the plugins in the Continuous Integration (CI) and Code Coverage sections.
Miscellaneous Tips
Writing Template Files
For an overview of writing template files for Mustache.jl, see Custom Template Files in the user guide.
Predicates
There are a few predicate functions for plugins that are occasionally used to answer questions like "does this Template have any code coverage plugins?". If you're implementing a plugin that fits into one of the following categories, it would be wise to implement the corresponding predicate function to return true for instances of your type.
PkgTemplates.needs_username — Function
needs_username(::Plugin) -> Bool
Determine whether or not a plugin needs a Git hosting service username to function correctly. If you are implementing a plugin that uses the user field of a Template, you should implement this function and return true.
source
PkgTemplates.is_ci — Function
is_ci(::Plugin) -> Bool
Determine whether or not a plugin is a CI plugin. If you are adding a CI plugin, you should implement this function and return true.
source
PkgTemplates.is_coverage — Function
is_coverage(::Plugin) -> Bool
Determine whether or not a plugin is a coverage plugin. If you are adding a coverage plugin, you should implement this function and return true.
source
Formatting Version Numbers
When writing configuration files for CI services, working with version numbers is often needed. There are a few convenience functions that can be used to make this a little bit easier.
PkgTemplates.format_version — Function
format_version(v::Union{VersionNumber, AbstractString}) -> String
Strip everything but the major and minor release from a VersionNumber. Strings are left in their original form.
source
PkgTemplates.collect_versions — Function
collect_versions(t::Template, versions::Vector) -> Vector{String}
Combine t's Julia version with versions, and format them as major.minor. This is useful for creating lists of versions to be included in CI configurations.
source

+end

There is also a default validate implementation for BasicPlugins, which checks that the plugin's source file exists, and throws an ArgumentError otherwise. If you want to extend the validation but keep the file existence check, use the invoke method as described above.

For more examples, see the plugins in the Continuous Integration (CI) and Code Coverage sections.

Miscellaneous Tips

Writing Template Files

For an overview of writing template files for Mustache.jl, see Custom Template Files in the user guide.

Predicates

There are a few predicate functions for plugins that are occasionally used to answer questions like "does this Template have any code coverage plugins?". If you're implementing a plugin that fits into one of the following categories, it would be wise to implement the corresponding predicate function to return true for instances of your type.

PkgTemplates.needs_username — Function
needs_username(::Plugin) -> Bool

Determine whether or not a plugin needs a Git hosting service username to function correctly. If you are implementing a plugin that uses the user field of a Template, you should implement this function and return true.

source
PkgTemplates.is_ci — Function
is_ci(::Plugin) -> Bool

Determine whether or not a plugin is a CI plugin. If you are adding a CI plugin, you should implement this function and return true.

source
PkgTemplates.is_coverage — Function
is_coverage(::Plugin) -> Bool

Determine whether or not a plugin is a coverage plugin. If you are adding a coverage plugin, you should implement this function and return true.

source

Formatting Version Numbers

When writing configuration files for CI services, working with version numbers is often needed. There are a few convenience functions that can be used to make this a little bit easier.

PkgTemplates.format_version — Function
format_version(v::Union{VersionNumber, AbstractString}) -> String

Strip everything but the major and minor release from a VersionNumber. Strings are left in their original form.

source
PkgTemplates.collect_versions — Function
collect_versions(t::Template, versions::Vector) -> Vector{String}

Combine t's Julia version with versions, and format them as major.minor. This is useful for creating lists of versions to be included in CI configurations.

source
diff --git a/dev/index.html b/dev/index.html index c7500ec..9a22db7 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · PkgTemplates.jl
Edit on GitHub

PkgTemplates

PkgTemplates creates new Julia packages in an easy, repeatable, and customizable way.

Documentation

If you're looking to create new packages, see the User Guide.

If you want to create new plugins, see the Developer Guide.

if you're trying to migrate from an older version of PkgTemplates, see Migrating To PkgTemplates 0.7+.

Index

+Home · PkgTemplates.jl
Edit on GitHub

PkgTemplates

PkgTemplates creates new Julia packages in an easy, repeatable, and customizable way.

Documentation

If you're looking to create new packages, see the User Guide.

If you want to create new plugins, see the Developer Guide.

if you're trying to migrate from an older version of PkgTemplates, see Migrating To PkgTemplates 0.7+.

Index

diff --git a/dev/migrating/index.html b/dev/migrating/index.html index cef28e9..51ab0c5 100644 --- a/dev/migrating/index.html +++ b/dev/migrating/index.html @@ -1,2 +1,2 @@ -Migrating To PkgTemplates 0.7+ · PkgTemplates.jl
Edit on GitHub

Migrating To PkgTemplates 0.7+

PkgTemplates 0.7 is a ground-up rewrite of the package with similar functionality but with updated APIs and internals. Here is a summary of things that existed in older versions but have been moved elsewhere or removed. However, it might be easier to just read the User Guide.

Template keywords

The recurring theme is "everything is a plugin now".

OldNew
license="ISC"plugins=[License(; name="ISC")]
develop=true *plugins=[Develop()]
git=falsedisable_defaults=[Git]
julia_version=v"1"julia=v"1"
ssh=trueplugins=[Git(; ssh=true)]
manifest=trueplugins=[Git(; manifest=true)]

* develop=true was the default setting, but it is no longer the default in PkgTemplates 0.7+.

Plugins

Aside from renamings, basically every plugin has had their constructors reworked. So if you are using anything non-default, you should consult the new docstring.

OldNew
GitHubPagesDocumenter{TravisCI}
GitLabPagesDocumenter{GitLabCI}

Package Generation

One less name to remember!

OldNew
generate(::Template, pkg::AbstractString)(::Template)(pkg::AbstractString)

Interactive Templates

Currently not implemented, but will be in the future.

Other Functions

Two less names to remember! Although it's unlikely that anyone used these.

OldNew
available_licensesView licenses on GitHub
show_licenseView licenses on GitHub

Custom Plugins

In addition to the changes in usage, custom plugins from older versions of PkgTemplates will not work in 0.7+. See the Developer Guide for more information on the new extension API.

+Migrating To PkgTemplates 0.7+ · PkgTemplates.jl
Edit on GitHub

Migrating To PkgTemplates 0.7+

PkgTemplates 0.7 is a ground-up rewrite of the package with similar functionality but with updated APIs and internals. Here is a summary of things that existed in older versions but have been moved elsewhere or removed. However, it might be easier to just read the User Guide.

Template keywords

The recurring theme is "everything is a plugin now".

OldNew
license="ISC"plugins=[License(; name="ISC")]
develop=true *plugins=[Develop()]
git=falsedisable_defaults=[Git]
julia_version=v"1"julia=v"1"
ssh=trueplugins=[Git(; ssh=true)]
manifest=trueplugins=[Git(; manifest=true)]

* develop=true was the default setting, but it is no longer the default in PkgTemplates 0.7+.

Plugins

Aside from renamings, basically every plugin has had their constructors reworked. So if you are using anything non-default, you should consult the new docstring.

OldNew
GitHubPagesDocumenter{TravisCI}
GitLabPagesDocumenter{GitLabCI}

Package Generation

One less name to remember!

OldNew
generate(::Template, pkg::AbstractString)(::Template)(pkg::AbstractString)

Interactive Templates

Currently not implemented, but will be in the future.

Other Functions

Two less names to remember! Although it's unlikely that anyone used these.

OldNew
available_licensesView licenses on GitHub
show_licenseView licenses on GitHub

Custom Plugins

In addition to the changes in usage, custom plugins from older versions of PkgTemplates will not work in 0.7+. See the Developer Guide for more information on the new extension API.

diff --git a/dev/search/index.html b/dev/search/index.html index 0259d16..68f1d55 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · PkgTemplates.jl

Loading search...

    +Search · PkgTemplates.jl

    Loading search...

      diff --git a/dev/user/index.html b/dev/user/index.html index 476789d..96c1a0b 100644 --- a/dev/user/index.html +++ b/dev/user/index.html @@ -3,11 +3,11 @@ t = Template() t("MyPkg")

      Template

      PkgTemplates.Template — Type
      Template(; kwargs...)

      A configuration used to generate packages.

      Keyword Arguments

      User Options

      • user::AbstractString="username": GitHub (or other code hosting service) username. The default value comes from the global Git config (github.user). If no value is obtained, many plugins that use this value will not work.
      • authors::Union{AbstractString, Vector{<:AbstractString}}="name <email>": Package authors. Like user, it takes its default value from the global Git config (user.name and user.email).

      Package Options

      • dir::AbstractString="~/.julia/dev": Directory to place packages in.
      • host::AbstractString="github.com": URL to the code hosting service where packages will reside.
      • julia::VersionNumber=v"1.0.0": Minimum allowed Julia version.

      Template Plugins

      • plugins::Vector{<:Plugin}=Plugin[]: A list of Plugins used by the template.
      • disable_defaults::Vector{DataType}=DataType[]: Default plugins to disable. The default plugins are ProjectFile, SrcDir, Tests, Readme, License, and Git. To override a default plugin instead of disabling it altogether, supply it via plugins.

      To create a package from a Template, use the following syntax:

      julia> t = Template();
 
-julia> t("PkgName")
      source

      Plugins

      Plugins add functionality to Templates. There are a number of plugins available to automate common boilerplate tasks.

      Default Plugins

      These plugins are included by default. They can be overridden by supplying another value via the plugins keyword, or disabled by supplying the type via the disable_defaults keyword.

      PkgTemplates.ProjectFile — Type
      ProjectFile(; version=v"0.1.0")

      Creates a Project.toml.

      Keyword Arguments

      • version::VersionNumber: The initial version of created packages.
      source
      PkgTemplates.SrcDir — Type
      SrcDir(; file="~/build/invenia/PkgTemplates.jl/templates/src/module.jl")

      Creates a module entrypoint.

      Keyword Arguments

      • file::AbstractString: Template file for src/<module>.jl.
      source
      PkgTemplates.Tests — Type
      Tests(; file="~/build/invenia/PkgTemplates.jl/templates/test/runtests.jl", project=false)

      Sets up testing for packages.

      Keyword Arguments

      • file::AbstractString: Template file for runtests.jl.
      • project::Bool: Whether or not to create a new project for tests (test/Project.toml). See here for more details.
      Note

      Managing test dependencies with test/Project.toml is only supported in Julia 1.2 and later.

      source
      PkgTemplates.Readme — Type
      Readme(;
+julia> t("PkgName")
      source

      Plugins

      Plugins add functionality to Templates. There are a number of plugins available to automate common boilerplate tasks.

      Default Plugins

      These plugins are included by default. They can be overridden by supplying another value via the plugins keyword, or disabled by supplying the type via the disable_defaults keyword.

      PkgTemplates.ProjectFile — Type
      ProjectFile(; version=v"0.1.0")

      Creates a Project.toml.

      Keyword Arguments

      • version::VersionNumber: The initial version of created packages.
      source
      PkgTemplates.SrcDir — Type
      SrcDir(; file="~/build/invenia/PkgTemplates.jl/templates/src/module.jl")

      Creates a module entrypoint.

      Keyword Arguments

      • file::AbstractString: Template file for src/<module>.jl.
      source
      PkgTemplates.Tests — Type
      Tests(; file="~/build/invenia/PkgTemplates.jl/templates/test/runtests.jl", project=false)

      Sets up testing for packages.

      Keyword Arguments

      • file::AbstractString: Template file for runtests.jl.
      • project::Bool: Whether or not to create a new project for tests (test/Project.toml). See here for more details.
      Note

      Managing test dependencies with test/Project.toml is only supported in Julia 1.2 and later.

      source
      PkgTemplates.Readme — Type
      Readme(;
     file="~/build/invenia/PkgTemplates.jl/templates/README.md",
     destination="README.md",
     inline_badges=false,
-)

      Creates a README file that contains badges for other included plugins.

      Keyword Arguments

      • file::AbstractString: Template file for the README.
      • destination::AbstractString: File destination, relative to the repository root. For example, values of "README" or "README.rst" might be desired.
      • inline_badges::Bool: Whether or not to put the badges on the same line as the package name.
      source
      PkgTemplates.License — Type
      License(; name="MIT", path=nothing, destination="LICENSE")

      Creates a license file.

      Keyword Arguments

      • name::AbstractString: Name of a license supported by PkgTemplates. Available licenses can be seen here.
      • path::Union{AbstractString, Nothing}: Path to a custom license file. This keyword takes priority over name.
      • destination::AbstractString: File destination, relative to the repository root. For example, "LICENSE.md" might be desired.
      source
      PkgTemplates.Git — Type
      Git(; ignore=String[], ssh=false, manifest=false, gpgsign=false)

      Creates a Git repository and a .gitignore file.

      Keyword Arguments

      • ignore::Vector{<:AbstractString}: Patterns to add to the .gitignore. See also: gitignore.
      • ssh::Bool: Whether or not to use SSH for the remote. If left unset, HTTPS is used.
      • manifest::Bool: Whether or not to commit Manifest.toml.
      • gpgsign::Bool: 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.
      source
      PkgTemplates.TagBot — Type
      TagBot(;
+)

      Creates a README file that contains badges for other included plugins.

      Keyword Arguments

      • file::AbstractString: Template file for the README.
      • destination::AbstractString: File destination, relative to the repository root. For example, values of "README" or "README.rst" might be desired.
      • inline_badges::Bool: Whether or not to put the badges on the same line as the package name.
      source
      PkgTemplates.License — Type
      License(; name="MIT", path=nothing, destination="LICENSE")

      Creates a license file.

      Keyword Arguments

      • name::AbstractString: Name of a license supported by PkgTemplates. Available licenses can be seen here.
      • path::Union{AbstractString, Nothing}: Path to a custom license file. This keyword takes priority over name.
      • destination::AbstractString: File destination, relative to the repository root. For example, "LICENSE.md" might be desired.
      source
      PkgTemplates.Git — Type
      Git(; ignore=String[], ssh=false, manifest=false, gpgsign=false)

      Creates a Git repository and a .gitignore file.

      Keyword Arguments

      • ignore::Vector{<:AbstractString}: Patterns to add to the .gitignore. See also: gitignore.
      • ssh::Bool: Whether or not to use SSH for the remote. If left unset, HTTPS is used.
      • manifest::Bool: Whether or not to commit Manifest.toml.
      • gpgsign::Bool: 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.
      source
      PkgTemplates.TagBot — Type
      TagBot(;
     file="~/build/invenia/PkgTemplates.jl/templates/github/workflows/TagBot.yml",
     destination="TagBot.yml",
     cron="0 * * * *",
@@ -22,7 +22,7 @@ julia> t("PkgName")

      Adds GitHub release support via TagBot.

      Keyword Arguments

      source
      PkgTemplates.Secret — Type
      Secret(name::AbstractString)

      Represents a GitHub repository secret. When converted to a string, yields ${{ secrets.<name> }}.

      source

      Continuous Integration (CI)

      These plugins will create the configuration files of common CI services for you.

      PkgTemplates.AppVeyor — Type
      AppVeyor(;
+)

      Adds GitHub release support via TagBot.

      Keyword Arguments

      • file::AbstractString: Template file for the workflow file.
      • destination::AbstractString: Destination of the workflow file, relative to .github/workflows.
      • cron::AbstractString: Cron expression for the schedule interval.
      • token::Secret: Name of the token secret to use.
      • ssh::Secret: Name of the SSH private key secret to use.
      • ssh_password::Secret: Name of the SSH key password secret to use.
      • changelog::AbstractString: Custom changelog template.
      • changelog_ignore::Vector{<:AbstractString}: Issue/pull request labels to ignore in the changelog.
      • gpg::Secret: Name of the GPG private key secret to use.
      • gpg_password::Secret: Name of the GPG private key password secret to use.
      • registry::AbstractString: Custom registry, in the format owner/repo.
      • branches::Bool: Whether not to enable the branches option.
      • dispatch::Bool: Whether or not to enable the dispatch option.
      • dispatch_delay::Int: Number of minutes to delay for dispatch events.
      source
      PkgTemplates.Secret — Type
      Secret(name::AbstractString)

      Represents a GitHub repository secret. When converted to a string, yields ${{ secrets.<name> }}.

      source

      Continuous Integration (CI)

      These plugins will create the configuration files of common CI services for you.

      PkgTemplates.AppVeyor — Type
      AppVeyor(;
     file="~/build/invenia/PkgTemplates.jl/templates/appveyor.yml",
     x86=false,
     coverage=true,
@@ -68,7 +68,7 @@ julia> t("PkgName")

      Sets up documentation generation via Documenter.jl. Documentation deployment depends on T, where T is some supported CI plugin, or Nothing to only support local documentation builds.

      Supported Type Parameters

      Keyword Arguments

      Note

      If deploying documentation with Travis CI, don't forget to complete the required configuration.

      source

      Miscellaneous

      PkgTemplates.Develop — Type
      Develop()

      Adds generated packages to the current environment by deving them. See the Pkg documentation here for more details.

      source
      PkgTemplates.CompatHelper — Type
      CompatHelper(;
+)

      Sets up documentation generation via Documenter.jl. Documentation deployment depends on T, where T is some supported CI plugin, or Nothing to only support local documentation builds.

      Supported Type Parameters

      Keyword Arguments

      • make_jl::AbstractString: Template file for make.jl.
      • index_md::AbstractString: Template file for index.md.
      • assets::Vector{<:AbstractString}: Extra assets for the generated site.
      • canonical_url::Union{Function, Nothing}: A function to generate the site's canonical URL. The default value will compute GitHub Pages and GitLab Pages URLs for TravisCI and GitLabCI, respectively. If set to nothing, no canonical URL is set.
      • makedocs_kwargs::Dict{Symbol}: Extra keyword arguments to be inserted into makedocs.
      Note

      If deploying documentation with Travis CI, don't forget to complete the required configuration.

      source

      Miscellaneous

      PkgTemplates.Develop — Type
      Develop()

      Adds generated packages to the current environment by deving them. See the Pkg documentation here for more details.

      source
      PkgTemplates.CompatHelper — Type
      CompatHelper(;
     file="~/build/invenia/PkgTemplates.jl/templates/github/workflows/CompatHelper.yml",
     destination="CompatHelper.yml",
     cron="0 0 * * *",
@@ -128,7 +128,7 @@ I have the following things:
 - Here's a thing: c
 
 - John is happy
-- Jane is sad

      Extending Existing Plugins

      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 user_view to supply whatever data is necessary for your use case.

      PkgTemplates.user_view — Function
      user_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}

      The same as view, but for use by package users for extension.

      Values returned by this function will override those from view when the keys are the same.

      source

      For example, suppose you were using the Readme plugin with a custom template file that looked like this:

      # {{PKG}}
+- Jane is sad

      Extending Existing Plugins

      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 user_view to supply whatever data is necessary for your use case.

      PkgTemplates.user_view — Function
      user_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}

      The same as view, but for use by package users for extension.

      Values returned by this function will override those from view when the keys are the same.

      source

      For example, suppose you were using the Readme plugin with a custom template file that looked like this:

      # {{PKG}}
 
 Created on *{{TODAY}}*.

      The view function supplies a value for PKG, but it does not supply a value for TODAY. Rather than override view, we can implement this function to get both the default values and whatever else we need to add.

      user_view(::Readme, ::Template, ::AbstractString) = Dict("TODAY" => today())

      Saving Templates

      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.

      Here's my recommendation for loading a template whenever it's needed:

      function template()
     @eval using PkgTemplates
@@ -140,4 +140,4 @@ open("template.jl", "w") do io
 end

      Then the template is just an include away:

      const t = include("template.jl")

      The only disadvantage to this approach is that the saved template is much less human-readable than code you wrote yourself.

      One more method of saving templates is to simply use the Serialization package in the standard library:

      const t = Template(; #= ... =#)
 using Serialization
 open(io -> serialize(io, t), "template.bin", "w")

      Then simply deserialize to load:

      using Serialization
-const t = open(deserialize, "template.bin")

      This approach has the same disadvantage as the previous one, and the serialization format is not guaranteed to be stable across Julia versions.

      +const t = open(deserialize, "template.bin")

      This approach has the same disadvantage as the previous one, and the serialization format is not guaranteed to be stable across Julia versions.