From dc08c19c275ecee7b8e2fb814ac2d107fd2a4929 Mon Sep 17 00:00:00 2001 From: autodocs Date: Thu, 7 Dec 2017 22:32:34 +0000 Subject: [PATCH] build based on 7e38c92 --- release-0.2/index.html | 8 +- release-0.2/pages/index.html | 2 +- release-0.2/pages/licenses.html | 2 +- release-0.2/pages/package_generation.html | 19 +- release-0.2/pages/plugin_development.html | 16 +- release-0.2/pages/plugins.html | 2 +- release-0.2/search_index.js | 162 ++---- stable/index.html | 8 +- stable/pages/index.html | 2 +- stable/pages/licenses.html | 2 +- stable/pages/package_generation.html | 19 +- stable/pages/plugin_development.html | 16 +- stable/pages/plugins.html | 2 +- stable/search_index.js | 162 ++---- v0.2.3/assets/arrow.svg | 63 +++ v0.2.3/assets/documenter.css | 577 ++++++++++++++++++++++ v0.2.3/assets/documenter.js | 129 +++++ v0.2.3/assets/search.js | 243 +++++++++ v0.2.3/index.html | 63 +++ v0.2.3/pages/index.html | 2 + v0.2.3/pages/licenses.html | 2 + v0.2.3/pages/package_generation.html | 38 ++ v0.2.3/pages/plugin_development.html | 91 ++++ v0.2.3/pages/plugins.html | 2 + v0.2.3/search.html | 2 + v0.2.3/search_index.js | 515 +++++++++++++++++++ v0.2.3/siteinfo.js | 1 + versions.js | 1 + 28 files changed, 1845 insertions(+), 306 deletions(-) create mode 100644 v0.2.3/assets/arrow.svg create mode 100644 v0.2.3/assets/documenter.css create mode 100644 v0.2.3/assets/documenter.js create mode 100644 v0.2.3/assets/search.js create mode 100644 v0.2.3/index.html create mode 100644 v0.2.3/pages/index.html create mode 100644 v0.2.3/pages/licenses.html create mode 100644 v0.2.3/pages/package_generation.html create mode 100644 v0.2.3/pages/plugin_development.html create mode 100644 v0.2.3/pages/plugins.html create mode 100644 v0.2.3/search.html create mode 100644 v0.2.3/search_index.js create mode 100644 v0.2.3/siteinfo.js diff --git a/release-0.2/index.html b/release-0.2/index.html index 3bb1fba..d094248 100644 --- a/release-0.2/index.html +++ b/release-0.2/index.html @@ -1,10 +1,10 @@ -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");
 
 julia> generate("MyPkg", t)
-INFO: Initialized git repo at /tmp/tmpHoGg7J/MyPkg
+INFO: Initialized git repo at /tmp/tmpDAskPD/MyPkg
 INFO: Made empty initial commit
 INFO: Set remote origin to https://github.com/myusername/MyPkg.jl
 INFO: Staged 6 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE
@@ -39,12 +39,12 @@ julia> t = Template(;
        );
 
 julia> generate("MyPkg", t; force=true, ssh=true)
-INFO: Initialized git repo at /tmp/tmpG4ogwp/MyPkg
+INFO: Initialized git repo at /tmp/tmplyg8Ll/MyPkg
 INFO: Applied git configuration
 INFO: Made empty initial 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: Moved temporary package directory into /home/travis/code/
 INFO: Finished
diff --git a/release-0.2/pages/index.html b/release-0.2/pages/index.html
index 4a8eee5..1561cfe 100644
--- a/release-0.2/pages/index.html
+++ b/release-0.2/pages/index.html
@@ -1,2 +1,2 @@
 
-Index · PkgTemplates.jl

Index

Index

+Index · PkgTemplates.jl

Index

Index

diff --git a/release-0.2/pages/licenses.html b/release-0.2/pages/licenses.html index e442c8f..38b1af3 100644 --- a/release-0.2/pages/licenses.html +++ b/release-0.2/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

available_licenses([io::IO]) -> Void

Print the names of all available licenses.

source

show_license

show_license([io::IO], license::AbstractString) -> Void

Print the text of license.

source

Helper Functions

read_license

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([io::IO]) -> Void

Print the names of all available licenses.

source
show_license([io::IO], license::AbstractString) -> Void

Print the text of license. Errors if the license is not found.

source

Helper Functions

read_license(license::AbstractString) -> String

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

source
diff --git a/release-0.2/pages/package_generation.html b/release-0.2/pages/package_generation.html index e85e981..15fe803 100644 --- a/release-0.2/pages/package_generation.html +++ b/release-0.2/pages/package_generation.html @@ -1,37 +1,38 @@ -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

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.

  • precompile::Bool=true: Whether or not to enable precompilation in generated packages.

  • julia_version::VersionNumber=VERSION: Minimum allowed Julia version.

  • requirements::Vector{<:AbstractString}=String[]: Package requirements. If there are duplicate requirements with different versions, i.e. ["PkgTemplates", "PkgTemplates 0.1"], an ArgumentError is thrown. Each entry in this array will be copied into the REQUIRE file of packages generated with this template.

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

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

source
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.generateFunction.
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

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.

  • precompile::Bool=true: Whether or not to enable precompilation in generated packages.

  • julia_version::VersionNumber=VERSION: Minimum allowed Julia version.

  • requirements::Vector{<:AbstractString}=String[]: Package requirements. If there are duplicate requirements with different versions, i.e. ["PkgTemplates", "PkgTemplates 0.1"], an ArgumentError is thrown. Each entry in this array will be copied into the REQUIRE file of packages generated with this template.

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

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

source
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.generateFunction.
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
generate_interactive(
+    backup_dir::AbstractString="",
+) -> 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 (this keyword is mostly for internal usage).

Notes

The package is generated entirely in a temporary directory and only moved into joinpath(t.dir, pkg_name) at the very end. In the case of an error, the temporary directory will contain leftovers, but the destination directory will remain untouched (this is especially helpful when force=true).

source
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

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(
     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

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(
     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

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(
     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

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(
     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

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(
     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

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(
     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/release-0.2/pages/plugin_development.html b/release-0.2/pages/plugin_development.html index 2a68e73..9edd381 100644 --- a/release-0.2/pages/plugin_development.html +++ b/release-0.2/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

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.

A plugin to be added to a Template, which adds some functionality or integration. New plugins should almost always extend GenericPlugin or CustomPlugin.

source

Generic Plugins

Generic plugins are plugins that add any number of patterns to the generated package's .gitignore, and have at most one associated file to generate.

Attributes

  • gitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.

  • src::Nullable{AbstractString}: Path to the file that will be copied into the generated package repository. If set to nothing, no file will be generated. When this defaults to an empty string, there should be a default file in defaults that will be copied. That file's name is usually the same as the plugin's name, except in all lowercase and with the .yml extension. If this is not the case, an interactive method needs to be implemented to call interactive(; file="file.ext").

  • dest::AbstractString: Path to the generated file, relative to the root of the generated package repository.

  • badges::Vector{Badge}: Array of Badges containing information used to create Markdown-formatted badges from the plugin. Entries will be run through substitute, so they may contain placeholder values.

  • view::Dict{String, Any}: Additional substitutions to make in both the plugin's badges and its associated file. See substitute for details.

Example

@auto_hash_equals struct MyPlugin <: GenericPlugin
     gitignore::Vector{AbstractString}
     src::Nullable{AbstractString}
     dest::AbstractString
@@ -34,7 +34,7 @@
     end
 end
 
-interactive(plugin_type::Type{MyPlugin}) = interactive(plugin_type; file="my-plugin.toml")

The above plugin ignores files ending with .mgp, copies defaults/my-plugin.toml by default, and creates a badge that links to the project on its own site, using the default substitutions with one addition: {{YEAR}} => Dates.year(Dates.today()). Since the default config template file doesn't follow the generic naming convention, we added another interactive method to correct the assumed filename.

source

Custom Plugins

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

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
 
@@ -44,7 +44,7 @@ interactive(plugin_type::Type{MyPlugin}) = interactive(plugin_type; file="m
         plugin::MyPlugin,
         template::Template,
         dir::AbstractString,
-        pkg_name::AbstractString
+        pkg_name::AbstractString,
     )
         if plugin.lucky
             text = substitute(
@@ -76,16 +76,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

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

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
interactive(
-    plugin_type::Type{P <: Plugin};
+) -> 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
interactive(
+    plugin_type::Type{<: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.badgesFunction.
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_fileFunction.
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

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.badgesFunction.
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_fileFunction.
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

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

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.formatFunction.
format(b::Badge)

Return badge's data formatted as a Markdown string.

source

version_floor

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

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.formatFunction.
format(b::Badge)

Return badge's data formatted as a Markdown string.

source

version_floor

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/release-0.2/pages/plugins.html b/release-0.2/pages/plugins.html index 068657a..c1aeb02 100644 --- a/release-0.2/pages/plugins.html +++ b/release-0.2/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

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

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

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

CodeCov(; config_file::Union{AbstractString, Void}=nothing) -> CodeCov

Add CodeCov to a template's plugins to optionally add a .codecov.yml configuration file to generated repositories, and an appropriate badge to the README. Also updates the .gitignore accordingly.

Keyword Arguments:

  • config_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.

source

Coveralls

Coveralls(; config_file::Union{AbstractString, Void}=nothing) -> 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

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

source

GitHubPages

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 secret sauce behing PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development.

Continuous Integration (CI)

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(; 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(; 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

Code Coverage

CodeCov(; config_file::Union{AbstractString, Void}=nothing) -> CodeCov

Add CodeCov to a template's plugins to optionally add a .codecov.yml configuration file to generated repositories, and an appropriate badge to the README. Also updates the .gitignore accordingly.

Keyword Arguments:

  • config_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.

source
Coveralls(; config_file::Union{AbstractString, Void}=nothing) -> 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

Documentation

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

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

source
diff --git a/release-0.2/search_index.js b/release-0.2/search_index.js index 4b3836a..fc7fcbe 100644 --- a/release-0.2/search_index.js +++ b/release-0.2/search_index.js @@ -85,7 +85,7 @@ var documenterSearchIndex = {"docs": [ "page": "Package Generation", "title": "PkgTemplates.generate", "category": "Function", - "text": "generate(\n pkg_name::AbstractString,\n t::Template;\n force::Bool=false,\n ssh::Bool=false,\n) -> Void\n\nGenerate a package named pkg_name from template.\n\nKeyword Arguments\n\nforce::Bool=false: Whether or not to overwrite old packages with the same name.\nssh::Bool=false: Whether or not to use SSH for the remote.\nbackup_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.\n\nNotes\n\nThe 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).\n\n\n\n" + "text": "generate(\n pkg_name::AbstractString,\n t::Template;\n force::Bool=false,\n ssh::Bool=false,\n backup_dir::AbstractString=\"\",\n) -> Void\n\nGenerate a package named pkg_name from template.\n\nKeyword Arguments\n\nforce::Bool=false: Whether or not to overwrite old packages with the same name.\nssh::Bool=false: Whether or not to use SSH for the remote.\nbackup_dir::AbstractString=\"\": Directory in which to store the generated package if t.dir is not a valid directory. If left unset, a temporary directory will be created (this keyword is mostly for internal usage).\n\nNotes\n\nThe 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).\n\n\n\n" }, { @@ -104,14 +104,6 @@ var documenterSearchIndex = {"docs": [ "text": "generate\ngenerate_interactive" }, -{ - "location": "pages/package_generation.html#Helper-Functions-1", - "page": "Package Generation", - "title": "Helper Functions", - "category": "section", - "text": "" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_entrypoint", "page": "Package Generation", @@ -120,14 +112,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_entrypoint(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate the module entrypoint in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose entrypoint we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_entrypoint-1", - "page": "Package Generation", - "title": "gen_entrypoint", - "category": "section", - "text": "gen_entrypoint" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_tests", "page": "Package Generation", @@ -136,14 +120,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_tests(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate the test directory and entrypoint in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose tests we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_tests-1", - "page": "Package Generation", - "title": "gen_tests", - "category": "section", - "text": "gen_tests" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_require", "page": "Package Generation", @@ -152,14 +128,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_require(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate the REQUIRE file in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose REQUIRE we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_require-1", - "page": "Package Generation", - "title": "gen_require", - "category": "section", - "text": "gen_require" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_readme", "page": "Package Generation", @@ -168,14 +136,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_readme(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate a README in the temp package directory with badges for each enabled plugin.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose README we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_readme-1", - "page": "Package Generation", - "title": "gen_readme", - "category": "section", - "text": "gen_readme" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_gitignore", "page": "Package Generation", @@ -184,14 +144,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_gitignore(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate a .gitignore in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose .gitignore we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_gitignore-1", - "page": "Package Generation", - "title": "gen_gitignore", - "category": "section", - "text": "gen_gitignore" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_license", "page": "Package Generation", @@ -201,11 +153,11 @@ var documenterSearchIndex = {"docs": [ }, { - "location": "pages/package_generation.html#gen_license-1", + "location": "pages/package_generation.html#Helper-Functions-1", "page": "Package Generation", - "title": "gen_license", + "title": "Helper Functions", "category": "section", - "text": "gen_license" + "text": "gen_entrypoint\ngen_tests\ngen_require\ngen_readme\ngen_gitignore\ngen_license" }, { @@ -221,7 +173,7 @@ var documenterSearchIndex = {"docs": [ "page": "Plugins", "title": "Plugins", "category": "section", - "text": "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." + "text": "Plugins are the secret sauce behing PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development." }, { @@ -232,14 +184,6 @@ var documenterSearchIndex = {"docs": [ "text": "TravisCI(; config_file::Union{AbstractString, Void}=\"\") -> TravisCI\n\nAdd TravisCI to a template's plugins to add a .travis.yml configuration file to generated repositories, and an appropriate badge to the README.\n\nKeyword Arguments:\n\nconfig_file::Union{AbstractString, Void}=\"\": Path to a custom .travis.yml. If nothing is supplied, no file will be generated.\n\n\n\n" }, -{ - "location": "pages/plugins.html#TravisCI-1", - "page": "Plugins", - "title": "TravisCI", - "category": "section", - "text": "TravisCI" -}, - { "location": "pages/plugins.html#PkgTemplates.AppVeyor", "page": "Plugins", @@ -248,14 +192,6 @@ var documenterSearchIndex = {"docs": [ "text": "AppVeyor(; config_file::Union{AbstractString, Void}=\"\") -> AppVeyor\n\nAdd AppVeyor to a template's plugins to add a .appveyor.yml configuration file to generated repositories, and an appropriate badge to the README.\n\nKeyword Arguments\n\nconfig_file::Union{AbstractString, Void}=\"\": Path to a custom .appveyor.yml. If nothing is supplied, no file will be generated.\n\n\n\n" }, -{ - "location": "pages/plugins.html#AppVeyor-1", - "page": "Plugins", - "title": "AppVeyor", - "category": "section", - "text": "AppVeyor" -}, - { "location": "pages/plugins.html#PkgTemplates.GitLabCI", "page": "Plugins", @@ -265,11 +201,11 @@ var documenterSearchIndex = {"docs": [ }, { - "location": "pages/plugins.html#GitLabCI-1", + "location": "pages/plugins.html#Continuous-Integration-(CI)-1", "page": "Plugins", - "title": "GitLabCI", + "title": "Continuous Integration (CI)", "category": "section", - "text": "GitLabCI" + "text": "TravisCI\nAppVeyor\nGitLabCI" }, { @@ -280,14 +216,6 @@ var documenterSearchIndex = {"docs": [ "text": "CodeCov(; config_file::Union{AbstractString, Void}=nothing) -> CodeCov\n\nAdd 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.\n\nKeyword Arguments:\n\nconfig_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.\n\n\n\n" }, -{ - "location": "pages/plugins.html#CodeCov-1", - "page": "Plugins", - "title": "CodeCov", - "category": "section", - "text": "CodeCov" -}, - { "location": "pages/plugins.html#PkgTemplates.Coveralls", "page": "Plugins", @@ -297,11 +225,11 @@ var documenterSearchIndex = {"docs": [ }, { - "location": "pages/plugins.html#Coveralls-1", + "location": "pages/plugins.html#Code-Coverage-1", "page": "Plugins", - "title": "Coveralls", + "title": "Code Coverage", "category": "section", - "text": "Coveralls" + "text": "CodeCov\nCoveralls" }, { @@ -312,28 +240,20 @@ var documenterSearchIndex = {"docs": [ "text": "Add a Documenter subtype to a template's plugins to add support for documentation generation via Documenter.jl.\n\n\n\n" }, -{ - "location": "pages/plugins.html#Documenter-1", - "page": "Plugins", - "title": "Documenter", - "category": "section", - "text": "Documenter" -}, - { "location": "pages/plugins.html#PkgTemplates.GitHubPages", "page": "Plugins", "title": "PkgTemplates.GitHubPages", "category": "Type", - "text": "GitHubPages(; assets::Vector{<:AbstractString}=String[]) -> GitHubPages\n\nAdd 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.\n\nKeyword Arguments\n\nassets::Vector{String}=String[]: Array of paths to Documenter asset files.\n\n\n\n" + "text": "GitHubPages(; assets::Vector{<:AbstractString}=String[]) -> GitHubPages\n\nAdd 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.\n\nKeyword Arguments\n\nassets::Vector{<:AbstractString}=String[]: Array of paths to Documenter asset files.\n\n\n\n" }, { - "location": "pages/plugins.html#GitHubPages-1", + "location": "pages/plugins.html#Documentation-1", "page": "Plugins", - "title": "GitHubPages", + "title": "Documentation", "category": "section", - "text": "GitHubPages" + "text": "Documenter\nGitHubPages" }, { @@ -344,12 +264,20 @@ var documenterSearchIndex = {"docs": [ "text": "CurrentModule = PkgTemplates" }, +{ + "location": "pages/plugin_development.html#PkgTemplates.Plugin", + "page": "Plugin Development", + "title": "PkgTemplates.Plugin", + "category": "Type", + "text": "A plugin to be added to a Template, which adds some functionality or integration. New plugins should almost always extend GenericPlugin or CustomPlugin.\n\n\n\n" +}, + { "location": "pages/plugin_development.html#Plugin-Development-1", "page": "Plugin Development", "title": "Plugin Development", "category": "section", - "text": "The best and easiest way to contribute to PkgTemplates is to write new plugins.There are two types of plugins: GenericPlugins and CustomPlugins." + "text": "The best and easiest way to contribute to PkgTemplates is to write new plugins.Plugin" }, { @@ -373,7 +301,7 @@ var documenterSearchIndex = {"docs": [ "page": "Plugin Development", "title": "PkgTemplates.CustomPlugin", "category": "Type", - "text": "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.\n\nAttributes\n\ngitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.\n\nExample\n\n@auto_hash_equals struct MyPlugin <: CustomPlugin\n gitignore::Vector{AbstractString}\n lucky::Bool\n\n MyPlugin() = new([], rand() > 0.8)\n\n function gen_plugin(\n plugin::MyPlugin,\n template::Template,\n dir::AbstractString,\n pkg_name::AbstractString\n )\n if plugin.lucky\n text = substitute(\n \"You got lucky with {{PKGNAME}}, {{USER}}!\",\n template,\n )\n gen_file(joinpath(dir, pkg_name, \".myplugin.yml\"), text)\n else\n println(\"Maybe next time.\")\n end\n end\n\n function badges(\n plugin::MyPlugin,\n user::AbstractString,\n pkg_name::AbstractString,\n )\n if plugin.lucky\n return [\n format(Badge(\n \"You got lucky!\",\n \"https://myplugin.com/badge.png\",\n \"https://myplugin.com/$user/$pkg_name.jl\",\n )),\n ]\n else\n return String[]\n end\n end\nend\n\ninteractive(plugin_type::Type{MyPlugin}) = MyPlugin()\n\nThis plugin doesn't do much, but it demonstrates how gen_plugin, badges and interactive can be implemented using substitute, gen_file, Badge, and format.\n\nDefining Template Files\n\nOften, 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.\n\nNote: Due to a bug in Mustache, conditionals can insert undesired newlines (more detail here).\n\n\n\n" + "text": "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.\n\nAttributes\n\ngitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.\n\nExample\n\n@auto_hash_equals struct MyPlugin <: CustomPlugin\n gitignore::Vector{AbstractString}\n lucky::Bool\n\n MyPlugin() = new([], rand() > 0.8)\n\n function gen_plugin(\n plugin::MyPlugin,\n template::Template,\n dir::AbstractString,\n pkg_name::AbstractString,\n )\n if plugin.lucky\n text = substitute(\n \"You got lucky with {{PKGNAME}}, {{USER}}!\",\n template,\n )\n gen_file(joinpath(dir, pkg_name, \".myplugin.yml\"), text)\n else\n println(\"Maybe next time.\")\n end\n end\n\n function badges(\n plugin::MyPlugin,\n user::AbstractString,\n pkg_name::AbstractString,\n )\n if plugin.lucky\n return [\n format(Badge(\n \"You got lucky!\",\n \"https://myplugin.com/badge.png\",\n \"https://myplugin.com/$user/$pkg_name.jl\",\n )),\n ]\n else\n return String[]\n end\n end\nend\n\ninteractive(plugin_type::Type{MyPlugin}) = MyPlugin()\n\nThis plugin doesn't do much, but it demonstrates how gen_plugin, badges and interactive can be implemented using substitute, gen_file, Badge, and format.\n\nDefining Template Files\n\nOften, 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.\n\nNote: Due to a bug in Mustache, conditionals can insert undesired newlines (more detail here).\n\n\n\n" }, { @@ -405,7 +333,7 @@ var documenterSearchIndex = {"docs": [ "page": "Plugin Development", "title": "PkgTemplates.interactive", "category": "Function", - "text": "interactive(\n plugin_type::Type{P <: Plugin};\n file::Union{AbstractString, Void}=\"\",\n) -> Plugin\n\nInteractively 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\").\n\n\n\n" + "text": "interactive(\n plugin_type::Type{<:Plugin};\n file::Union{AbstractString, Void}=\"\",\n) -> Plugin\n\nInteractively 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\").\n\n\n\n" }, { @@ -528,14 +456,6 @@ var documenterSearchIndex = {"docs": [ "text": "CurrentModule = PkgTemplates" }, -{ - "location": "pages/licenses.html#Licenses-1", - "page": "Licenses", - "title": "Licenses", - "category": "section", - "text": "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." -}, - { "location": "pages/licenses.html#PkgTemplates.available_licenses", "page": "Licenses", @@ -544,36 +464,20 @@ var documenterSearchIndex = {"docs": [ "text": "available_licenses([io::IO]) -> Void\n\nPrint the names of all available licenses.\n\n\n\n" }, -{ - "location": "pages/licenses.html#available_licenses-1", - "page": "Licenses", - "title": "available_licenses", - "category": "section", - "text": "available_licenses" -}, - { "location": "pages/licenses.html#PkgTemplates.show_license", "page": "Licenses", "title": "PkgTemplates.show_license", "category": "Function", - "text": "show_license([io::IO], license::AbstractString) -> Void\n\nPrint the text of license.\n\n\n\n" + "text": "show_license([io::IO], license::AbstractString) -> Void\n\nPrint the text of license. Errors if the license is not found.\n\n\n\n" }, { - "location": "pages/licenses.html#show_license-1", + "location": "pages/licenses.html#Licenses-1", "page": "Licenses", - "title": "show_license", + "title": "Licenses", "category": "section", - "text": "show_license" -}, - -{ - "location": "pages/licenses.html#Helper-Functions-1", - "page": "Licenses", - "title": "Helper Functions", - "category": "section", - "text": "" + "text": "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\nshow_license" }, { @@ -581,13 +485,13 @@ var documenterSearchIndex = {"docs": [ "page": "Licenses", "title": "PkgTemplates.read_license", "category": "Function", - "text": "read_license(license::AbstractString) -> String\n\nReturns the contents of license. Errors if it is not found. Use available_licenses to view available licenses.\n\n\n\n" + "text": "read_license(license::AbstractString) -> String\n\nReturns the contents of license. Errors if the license is not found. Use available_licenses to view available licenses.\n\n\n\n" }, { - "location": "pages/licenses.html#read_license-1", + "location": "pages/licenses.html#Helper-Functions-1", "page": "Licenses", - "title": "read_license", + "title": "Helper Functions", "category": "section", "text": "read_license" }, diff --git a/stable/index.html b/stable/index.html index 3bb1fba..d094248 100644 --- a/stable/index.html +++ b/stable/index.html @@ -1,10 +1,10 @@ -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");
 
 julia> generate("MyPkg", t)
-INFO: Initialized git repo at /tmp/tmpHoGg7J/MyPkg
+INFO: Initialized git repo at /tmp/tmpDAskPD/MyPkg
 INFO: Made empty initial commit
 INFO: Set remote origin to https://github.com/myusername/MyPkg.jl
 INFO: Staged 6 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE
@@ -39,12 +39,12 @@ julia> t = Template(;
        );
 
 julia> generate("MyPkg", t; force=true, ssh=true)
-INFO: Initialized git repo at /tmp/tmpG4ogwp/MyPkg
+INFO: Initialized git repo at /tmp/tmplyg8Ll/MyPkg
 INFO: Applied git configuration
 INFO: Made empty initial 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: Moved temporary package directory into /home/travis/code/
 INFO: Finished
diff --git a/stable/pages/index.html b/stable/pages/index.html
index 4a8eee5..1561cfe 100644
--- a/stable/pages/index.html
+++ b/stable/pages/index.html
@@ -1,2 +1,2 @@
 
-Index · PkgTemplates.jl

Index

Index

+Index · PkgTemplates.jl

Index

Index

diff --git a/stable/pages/licenses.html b/stable/pages/licenses.html index e442c8f..38b1af3 100644 --- a/stable/pages/licenses.html +++ b/stable/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

available_licenses([io::IO]) -> Void

Print the names of all available licenses.

source

show_license

show_license([io::IO], license::AbstractString) -> Void

Print the text of license.

source

Helper Functions

read_license

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([io::IO]) -> Void

Print the names of all available licenses.

source
show_license([io::IO], license::AbstractString) -> Void

Print the text of license. Errors if the license is not found.

source

Helper Functions

read_license(license::AbstractString) -> String

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

source
diff --git a/stable/pages/package_generation.html b/stable/pages/package_generation.html index e85e981..15fe803 100644 --- a/stable/pages/package_generation.html +++ b/stable/pages/package_generation.html @@ -1,37 +1,38 @@ -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

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.

  • precompile::Bool=true: Whether or not to enable precompilation in generated packages.

  • julia_version::VersionNumber=VERSION: Minimum allowed Julia version.

  • requirements::Vector{<:AbstractString}=String[]: Package requirements. If there are duplicate requirements with different versions, i.e. ["PkgTemplates", "PkgTemplates 0.1"], an ArgumentError is thrown. Each entry in this array will be copied into the REQUIRE file of packages generated with this template.

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

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

source
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.generateFunction.
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

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.

  • precompile::Bool=true: Whether or not to enable precompilation in generated packages.

  • julia_version::VersionNumber=VERSION: Minimum allowed Julia version.

  • requirements::Vector{<:AbstractString}=String[]: Package requirements. If there are duplicate requirements with different versions, i.e. ["PkgTemplates", "PkgTemplates 0.1"], an ArgumentError is thrown. Each entry in this array will be copied into the REQUIRE file of packages generated with this template.

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

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

source
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.generateFunction.
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
generate_interactive(
+    backup_dir::AbstractString="",
+) -> 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 (this keyword is mostly for internal usage).

Notes

The package is generated entirely in a temporary directory and only moved into joinpath(t.dir, pkg_name) at the very end. In the case of an error, the temporary directory will contain leftovers, but the destination directory will remain untouched (this is especially helpful when force=true).

source
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

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(
     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

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(
     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

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(
     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

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(
     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

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(
     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

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(
     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/stable/pages/plugin_development.html b/stable/pages/plugin_development.html index 2a68e73..9edd381 100644 --- a/stable/pages/plugin_development.html +++ b/stable/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

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.

A plugin to be added to a Template, which adds some functionality or integration. New plugins should almost always extend GenericPlugin or CustomPlugin.

source

Generic Plugins

Generic plugins are plugins that add any number of patterns to the generated package's .gitignore, and have at most one associated file to generate.

Attributes

  • gitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.

  • src::Nullable{AbstractString}: Path to the file that will be copied into the generated package repository. If set to nothing, no file will be generated. When this defaults to an empty string, there should be a default file in defaults that will be copied. That file's name is usually the same as the plugin's name, except in all lowercase and with the .yml extension. If this is not the case, an interactive method needs to be implemented to call interactive(; file="file.ext").

  • dest::AbstractString: Path to the generated file, relative to the root of the generated package repository.

  • badges::Vector{Badge}: Array of Badges containing information used to create Markdown-formatted badges from the plugin. Entries will be run through substitute, so they may contain placeholder values.

  • view::Dict{String, Any}: Additional substitutions to make in both the plugin's badges and its associated file. See substitute for details.

Example

@auto_hash_equals struct MyPlugin <: GenericPlugin
     gitignore::Vector{AbstractString}
     src::Nullable{AbstractString}
     dest::AbstractString
@@ -34,7 +34,7 @@
     end
 end
 
-interactive(plugin_type::Type{MyPlugin}) = interactive(plugin_type; file="my-plugin.toml")

The above plugin ignores files ending with .mgp, copies defaults/my-plugin.toml by default, and creates a badge that links to the project on its own site, using the default substitutions with one addition: {{YEAR}} => Dates.year(Dates.today()). Since the default config template file doesn't follow the generic naming convention, we added another interactive method to correct the assumed filename.

source

Custom Plugins

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

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
 
@@ -44,7 +44,7 @@ interactive(plugin_type::Type{MyPlugin}) = interactive(plugin_type; file="m
         plugin::MyPlugin,
         template::Template,
         dir::AbstractString,
-        pkg_name::AbstractString
+        pkg_name::AbstractString,
     )
         if plugin.lucky
             text = substitute(
@@ -76,16 +76,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

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

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
interactive(
-    plugin_type::Type{P <: Plugin};
+) -> 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
interactive(
+    plugin_type::Type{<: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.badgesFunction.
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_fileFunction.
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

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.badgesFunction.
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_fileFunction.
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

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

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.formatFunction.
format(b::Badge)

Return badge's data formatted as a Markdown string.

source

version_floor

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

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.formatFunction.
format(b::Badge)

Return badge's data formatted as a Markdown string.

source

version_floor

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/stable/pages/plugins.html b/stable/pages/plugins.html index 068657a..c1aeb02 100644 --- a/stable/pages/plugins.html +++ b/stable/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

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

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

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

CodeCov(; config_file::Union{AbstractString, Void}=nothing) -> CodeCov

Add CodeCov to a template's plugins to optionally add a .codecov.yml configuration file to generated repositories, and an appropriate badge to the README. Also updates the .gitignore accordingly.

Keyword Arguments:

  • config_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.

source

Coveralls

Coveralls(; config_file::Union{AbstractString, Void}=nothing) -> 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

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

source

GitHubPages

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 secret sauce behing PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development.

Continuous Integration (CI)

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(; 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(; 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

Code Coverage

CodeCov(; config_file::Union{AbstractString, Void}=nothing) -> CodeCov

Add CodeCov to a template's plugins to optionally add a .codecov.yml configuration file to generated repositories, and an appropriate badge to the README. Also updates the .gitignore accordingly.

Keyword Arguments:

  • config_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.

source
Coveralls(; config_file::Union{AbstractString, Void}=nothing) -> 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

Documentation

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

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

source
diff --git a/stable/search_index.js b/stable/search_index.js index 4b3836a..fc7fcbe 100644 --- a/stable/search_index.js +++ b/stable/search_index.js @@ -85,7 +85,7 @@ var documenterSearchIndex = {"docs": [ "page": "Package Generation", "title": "PkgTemplates.generate", "category": "Function", - "text": "generate(\n pkg_name::AbstractString,\n t::Template;\n force::Bool=false,\n ssh::Bool=false,\n) -> Void\n\nGenerate a package named pkg_name from template.\n\nKeyword Arguments\n\nforce::Bool=false: Whether or not to overwrite old packages with the same name.\nssh::Bool=false: Whether or not to use SSH for the remote.\nbackup_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.\n\nNotes\n\nThe 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).\n\n\n\n" + "text": "generate(\n pkg_name::AbstractString,\n t::Template;\n force::Bool=false,\n ssh::Bool=false,\n backup_dir::AbstractString=\"\",\n) -> Void\n\nGenerate a package named pkg_name from template.\n\nKeyword Arguments\n\nforce::Bool=false: Whether or not to overwrite old packages with the same name.\nssh::Bool=false: Whether or not to use SSH for the remote.\nbackup_dir::AbstractString=\"\": Directory in which to store the generated package if t.dir is not a valid directory. If left unset, a temporary directory will be created (this keyword is mostly for internal usage).\n\nNotes\n\nThe 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).\n\n\n\n" }, { @@ -104,14 +104,6 @@ var documenterSearchIndex = {"docs": [ "text": "generate\ngenerate_interactive" }, -{ - "location": "pages/package_generation.html#Helper-Functions-1", - "page": "Package Generation", - "title": "Helper Functions", - "category": "section", - "text": "" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_entrypoint", "page": "Package Generation", @@ -120,14 +112,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_entrypoint(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate the module entrypoint in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose entrypoint we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_entrypoint-1", - "page": "Package Generation", - "title": "gen_entrypoint", - "category": "section", - "text": "gen_entrypoint" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_tests", "page": "Package Generation", @@ -136,14 +120,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_tests(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate the test directory and entrypoint in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose tests we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_tests-1", - "page": "Package Generation", - "title": "gen_tests", - "category": "section", - "text": "gen_tests" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_require", "page": "Package Generation", @@ -152,14 +128,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_require(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate the REQUIRE file in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose REQUIRE we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_require-1", - "page": "Package Generation", - "title": "gen_require", - "category": "section", - "text": "gen_require" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_readme", "page": "Package Generation", @@ -168,14 +136,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_readme(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate a README in the temp package directory with badges for each enabled plugin.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose README we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_readme-1", - "page": "Package Generation", - "title": "gen_readme", - "category": "section", - "text": "gen_readme" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_gitignore", "page": "Package Generation", @@ -184,14 +144,6 @@ var documenterSearchIndex = {"docs": [ "text": "gen_gitignore(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate a .gitignore in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose .gitignore we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" }, -{ - "location": "pages/package_generation.html#gen_gitignore-1", - "page": "Package Generation", - "title": "gen_gitignore", - "category": "section", - "text": "gen_gitignore" -}, - { "location": "pages/package_generation.html#PkgTemplates.gen_license", "page": "Package Generation", @@ -201,11 +153,11 @@ var documenterSearchIndex = {"docs": [ }, { - "location": "pages/package_generation.html#gen_license-1", + "location": "pages/package_generation.html#Helper-Functions-1", "page": "Package Generation", - "title": "gen_license", + "title": "Helper Functions", "category": "section", - "text": "gen_license" + "text": "gen_entrypoint\ngen_tests\ngen_require\ngen_readme\ngen_gitignore\ngen_license" }, { @@ -221,7 +173,7 @@ var documenterSearchIndex = {"docs": [ "page": "Plugins", "title": "Plugins", "category": "section", - "text": "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." + "text": "Plugins are the secret sauce behing PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development." }, { @@ -232,14 +184,6 @@ var documenterSearchIndex = {"docs": [ "text": "TravisCI(; config_file::Union{AbstractString, Void}=\"\") -> TravisCI\n\nAdd TravisCI to a template's plugins to add a .travis.yml configuration file to generated repositories, and an appropriate badge to the README.\n\nKeyword Arguments:\n\nconfig_file::Union{AbstractString, Void}=\"\": Path to a custom .travis.yml. If nothing is supplied, no file will be generated.\n\n\n\n" }, -{ - "location": "pages/plugins.html#TravisCI-1", - "page": "Plugins", - "title": "TravisCI", - "category": "section", - "text": "TravisCI" -}, - { "location": "pages/plugins.html#PkgTemplates.AppVeyor", "page": "Plugins", @@ -248,14 +192,6 @@ var documenterSearchIndex = {"docs": [ "text": "AppVeyor(; config_file::Union{AbstractString, Void}=\"\") -> AppVeyor\n\nAdd AppVeyor to a template's plugins to add a .appveyor.yml configuration file to generated repositories, and an appropriate badge to the README.\n\nKeyword Arguments\n\nconfig_file::Union{AbstractString, Void}=\"\": Path to a custom .appveyor.yml. If nothing is supplied, no file will be generated.\n\n\n\n" }, -{ - "location": "pages/plugins.html#AppVeyor-1", - "page": "Plugins", - "title": "AppVeyor", - "category": "section", - "text": "AppVeyor" -}, - { "location": "pages/plugins.html#PkgTemplates.GitLabCI", "page": "Plugins", @@ -265,11 +201,11 @@ var documenterSearchIndex = {"docs": [ }, { - "location": "pages/plugins.html#GitLabCI-1", + "location": "pages/plugins.html#Continuous-Integration-(CI)-1", "page": "Plugins", - "title": "GitLabCI", + "title": "Continuous Integration (CI)", "category": "section", - "text": "GitLabCI" + "text": "TravisCI\nAppVeyor\nGitLabCI" }, { @@ -280,14 +216,6 @@ var documenterSearchIndex = {"docs": [ "text": "CodeCov(; config_file::Union{AbstractString, Void}=nothing) -> CodeCov\n\nAdd 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.\n\nKeyword Arguments:\n\nconfig_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.\n\n\n\n" }, -{ - "location": "pages/plugins.html#CodeCov-1", - "page": "Plugins", - "title": "CodeCov", - "category": "section", - "text": "CodeCov" -}, - { "location": "pages/plugins.html#PkgTemplates.Coveralls", "page": "Plugins", @@ -297,11 +225,11 @@ var documenterSearchIndex = {"docs": [ }, { - "location": "pages/plugins.html#Coveralls-1", + "location": "pages/plugins.html#Code-Coverage-1", "page": "Plugins", - "title": "Coveralls", + "title": "Code Coverage", "category": "section", - "text": "Coveralls" + "text": "CodeCov\nCoveralls" }, { @@ -312,28 +240,20 @@ var documenterSearchIndex = {"docs": [ "text": "Add a Documenter subtype to a template's plugins to add support for documentation generation via Documenter.jl.\n\n\n\n" }, -{ - "location": "pages/plugins.html#Documenter-1", - "page": "Plugins", - "title": "Documenter", - "category": "section", - "text": "Documenter" -}, - { "location": "pages/plugins.html#PkgTemplates.GitHubPages", "page": "Plugins", "title": "PkgTemplates.GitHubPages", "category": "Type", - "text": "GitHubPages(; assets::Vector{<:AbstractString}=String[]) -> GitHubPages\n\nAdd 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.\n\nKeyword Arguments\n\nassets::Vector{String}=String[]: Array of paths to Documenter asset files.\n\n\n\n" + "text": "GitHubPages(; assets::Vector{<:AbstractString}=String[]) -> GitHubPages\n\nAdd 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.\n\nKeyword Arguments\n\nassets::Vector{<:AbstractString}=String[]: Array of paths to Documenter asset files.\n\n\n\n" }, { - "location": "pages/plugins.html#GitHubPages-1", + "location": "pages/plugins.html#Documentation-1", "page": "Plugins", - "title": "GitHubPages", + "title": "Documentation", "category": "section", - "text": "GitHubPages" + "text": "Documenter\nGitHubPages" }, { @@ -344,12 +264,20 @@ var documenterSearchIndex = {"docs": [ "text": "CurrentModule = PkgTemplates" }, +{ + "location": "pages/plugin_development.html#PkgTemplates.Plugin", + "page": "Plugin Development", + "title": "PkgTemplates.Plugin", + "category": "Type", + "text": "A plugin to be added to a Template, which adds some functionality or integration. New plugins should almost always extend GenericPlugin or CustomPlugin.\n\n\n\n" +}, + { "location": "pages/plugin_development.html#Plugin-Development-1", "page": "Plugin Development", "title": "Plugin Development", "category": "section", - "text": "The best and easiest way to contribute to PkgTemplates is to write new plugins.There are two types of plugins: GenericPlugins and CustomPlugins." + "text": "The best and easiest way to contribute to PkgTemplates is to write new plugins.Plugin" }, { @@ -373,7 +301,7 @@ var documenterSearchIndex = {"docs": [ "page": "Plugin Development", "title": "PkgTemplates.CustomPlugin", "category": "Type", - "text": "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.\n\nAttributes\n\ngitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.\n\nExample\n\n@auto_hash_equals struct MyPlugin <: CustomPlugin\n gitignore::Vector{AbstractString}\n lucky::Bool\n\n MyPlugin() = new([], rand() > 0.8)\n\n function gen_plugin(\n plugin::MyPlugin,\n template::Template,\n dir::AbstractString,\n pkg_name::AbstractString\n )\n if plugin.lucky\n text = substitute(\n \"You got lucky with {{PKGNAME}}, {{USER}}!\",\n template,\n )\n gen_file(joinpath(dir, pkg_name, \".myplugin.yml\"), text)\n else\n println(\"Maybe next time.\")\n end\n end\n\n function badges(\n plugin::MyPlugin,\n user::AbstractString,\n pkg_name::AbstractString,\n )\n if plugin.lucky\n return [\n format(Badge(\n \"You got lucky!\",\n \"https://myplugin.com/badge.png\",\n \"https://myplugin.com/$user/$pkg_name.jl\",\n )),\n ]\n else\n return String[]\n end\n end\nend\n\ninteractive(plugin_type::Type{MyPlugin}) = MyPlugin()\n\nThis plugin doesn't do much, but it demonstrates how gen_plugin, badges and interactive can be implemented using substitute, gen_file, Badge, and format.\n\nDefining Template Files\n\nOften, 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.\n\nNote: Due to a bug in Mustache, conditionals can insert undesired newlines (more detail here).\n\n\n\n" + "text": "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.\n\nAttributes\n\ngitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.\n\nExample\n\n@auto_hash_equals struct MyPlugin <: CustomPlugin\n gitignore::Vector{AbstractString}\n lucky::Bool\n\n MyPlugin() = new([], rand() > 0.8)\n\n function gen_plugin(\n plugin::MyPlugin,\n template::Template,\n dir::AbstractString,\n pkg_name::AbstractString,\n )\n if plugin.lucky\n text = substitute(\n \"You got lucky with {{PKGNAME}}, {{USER}}!\",\n template,\n )\n gen_file(joinpath(dir, pkg_name, \".myplugin.yml\"), text)\n else\n println(\"Maybe next time.\")\n end\n end\n\n function badges(\n plugin::MyPlugin,\n user::AbstractString,\n pkg_name::AbstractString,\n )\n if plugin.lucky\n return [\n format(Badge(\n \"You got lucky!\",\n \"https://myplugin.com/badge.png\",\n \"https://myplugin.com/$user/$pkg_name.jl\",\n )),\n ]\n else\n return String[]\n end\n end\nend\n\ninteractive(plugin_type::Type{MyPlugin}) = MyPlugin()\n\nThis plugin doesn't do much, but it demonstrates how gen_plugin, badges and interactive can be implemented using substitute, gen_file, Badge, and format.\n\nDefining Template Files\n\nOften, 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.\n\nNote: Due to a bug in Mustache, conditionals can insert undesired newlines (more detail here).\n\n\n\n" }, { @@ -405,7 +333,7 @@ var documenterSearchIndex = {"docs": [ "page": "Plugin Development", "title": "PkgTemplates.interactive", "category": "Function", - "text": "interactive(\n plugin_type::Type{P <: Plugin};\n file::Union{AbstractString, Void}=\"\",\n) -> Plugin\n\nInteractively 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\").\n\n\n\n" + "text": "interactive(\n plugin_type::Type{<:Plugin};\n file::Union{AbstractString, Void}=\"\",\n) -> Plugin\n\nInteractively 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\").\n\n\n\n" }, { @@ -528,14 +456,6 @@ var documenterSearchIndex = {"docs": [ "text": "CurrentModule = PkgTemplates" }, -{ - "location": "pages/licenses.html#Licenses-1", - "page": "Licenses", - "title": "Licenses", - "category": "section", - "text": "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." -}, - { "location": "pages/licenses.html#PkgTemplates.available_licenses", "page": "Licenses", @@ -544,36 +464,20 @@ var documenterSearchIndex = {"docs": [ "text": "available_licenses([io::IO]) -> Void\n\nPrint the names of all available licenses.\n\n\n\n" }, -{ - "location": "pages/licenses.html#available_licenses-1", - "page": "Licenses", - "title": "available_licenses", - "category": "section", - "text": "available_licenses" -}, - { "location": "pages/licenses.html#PkgTemplates.show_license", "page": "Licenses", "title": "PkgTemplates.show_license", "category": "Function", - "text": "show_license([io::IO], license::AbstractString) -> Void\n\nPrint the text of license.\n\n\n\n" + "text": "show_license([io::IO], license::AbstractString) -> Void\n\nPrint the text of license. Errors if the license is not found.\n\n\n\n" }, { - "location": "pages/licenses.html#show_license-1", + "location": "pages/licenses.html#Licenses-1", "page": "Licenses", - "title": "show_license", + "title": "Licenses", "category": "section", - "text": "show_license" -}, - -{ - "location": "pages/licenses.html#Helper-Functions-1", - "page": "Licenses", - "title": "Helper Functions", - "category": "section", - "text": "" + "text": "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\nshow_license" }, { @@ -581,13 +485,13 @@ var documenterSearchIndex = {"docs": [ "page": "Licenses", "title": "PkgTemplates.read_license", "category": "Function", - "text": "read_license(license::AbstractString) -> String\n\nReturns the contents of license. Errors if it is not found. Use available_licenses to view available licenses.\n\n\n\n" + "text": "read_license(license::AbstractString) -> String\n\nReturns the contents of license. Errors if the license is not found. Use available_licenses to view available licenses.\n\n\n\n" }, { - "location": "pages/licenses.html#read_license-1", + "location": "pages/licenses.html#Helper-Functions-1", "page": "Licenses", - "title": "read_license", + "title": "Helper Functions", "category": "section", "text": "read_license" }, diff --git a/v0.2.3/assets/arrow.svg b/v0.2.3/assets/arrow.svg new file mode 100644 index 0000000..ee2798d --- /dev/null +++ b/v0.2.3/assets/arrow.svg @@ -0,0 +1,63 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/v0.2.3/assets/documenter.css b/v0.2.3/assets/documenter.css new file mode 100644 index 0000000..0aa36a9 --- /dev/null +++ b/v0.2.3/assets/documenter.css @@ -0,0 +1,577 @@ +/* + * The default CSS style for Documenter.jl generated sites + * + * Heavily inspired by the Julia Sphinx theme + * https://github.com/JuliaLang/JuliaDoc + * which extends the sphinx_rtd_theme + * https://github.com/snide/sphinx_rtd_theme + * + * Part of Documenter.jl + * https://github.com/JuliaDocs/Documenter.jl + * + * License: MIT + */ + +/* fonts */ +body, input { + font-family: 'Lato', 'Helvetica Neue', Arial, sans-serif; + font-size: 16px; + color: #222; + text-rendering: optimizeLegibility; +} + +pre, code, kbd { + font-family: 'Roboto Mono', Monaco, courier, monospace; + font-size: 0.90em; +} + +pre code { + font-size: 1em; +} + +a { + color: #2980b9; + text-decoration: none; +} + +a:hover { + color: #3091d1; +} + +a:visited { + color: #9b59b6; +} + +body { + line-height: 1.5; +} + +h1 { + font-size: 1.75em; +} + +/* Unless the

the is very first thing on the page (i.e. the second element + * in the
, * after the
, we add some additional styling to it + * to make it stand out a bit more. This way we get a reasonable fallback if CSS3 + * selectors are not supported in the browser. + */ +article > h1:not(:nth-child(2)) { + margin: 2.5em 0 0; + padding-bottom: 0.30em; + border-bottom: 1px solid #e5e5e5; +} +h2 { + font-size: 1.50em; + margin: 2.3em 0 0; + padding-bottom: 0.25em; + border-bottom: 1px solid #e5e5e5; +} +h3 { + font-size: 1.25em; + margin: 2.0em 0 0; +} +h4 { font-size: 1.15em; } +h5 { font-size: 1.10em; } +h6 { font-size: 1em; } + +h4, h5, h6 { + margin-top: 1.5em; + margin-bottom: 1em; +} + +img { + max-width: 100%; +} + +table { + border-collapse: collapse; + margin: 1em 0; +} + +th, td { + border: 1px solid #e1e4e5; + padding: 0.5em 1em; +} + +th { + border-bottom-width: 2px; +} + +tr:nth-child(even) { + background-color: #f3f6f6; +} + +hr { + border: 0; + border-top: 1px solid #e5e5e5; +} + +/* Inline code and code blocks */ + +code { + padding: 0.1em; + background-color: rgba(0,0,0,.04); + border-radius: 3px; +} + +pre { + background-color: #f5f5f5; + border: 1px solid #dddddd; + border-radius: 3px; + padding: 0.5em; + overflow: auto; +} + +pre code { + padding: 0; + background-color: initial; +} + +kbd { + font-size: 0.70em; + display: inline-block; + padding: 0.1em 0.5em 0.4em 0.5em; + line-height: 1.0em; + color: #444d56; + vertical-align: middle; + background-color: #fafbfc; + border: solid 1px #c6cbd1; + border-bottom-color: #959da5; + border-radius: 3px; + box-shadow: inset 0 -1px 0 #959da5; +} + +/* Headers in admonitions and docstrings */ +.admonition h1, +article section.docstring h1 { + font-size: 1.25em; +} + +.admonition h2, +article section.docstring h2 { + font-size: 1.10em; +} + +.admonition h3, +.admonition h4, +.admonition h5, +.admonition h6, +article section.docstring h3, +article section.docstring h4, +article section.docstring h5, +article section.docstring h6 { + font-size: 1em; +} + +/* Navigation */ +nav.toc { + position: fixed; + top: 0; + left: 0; + bottom: 0; + width: 20em; + overflow-y: auto; + padding: 1em 0; + background-color: #fcfcfc; + box-shadow: inset -14px 0px 5px -12px rgb(210,210,210); +} + +nav.toc .logo { + margin: 0 auto; + display: block; + max-height: 6em; + max-width: 18em; +} + +nav.toc h1 { + text-align: center; + margin-top: .57em; + margin-bottom: 0; +} + +nav.toc select { + display: block; + height: 2em; + padding: 0 1.6em 0 1em; + min-width: 7em; + max-width: 90%; + max-width: calc(100% - 5em); + margin: 0 auto; + font-size: .83em; + border: 1px solid #c9c9c9; + border-radius: 1em; + + /* TODO: doesn't seem to be centered on Safari */ + text-align: center; + text-align-last: center; + + appearance: none; + -moz-appearance: none; + -webkit-appearance: none; + + background: white url("arrow.svg"); + background-size: 1.155em; + background-repeat: no-repeat; + background-position: right; +} + +nav.toc select:hover { + border: 1px solid #a0a0a0; +} + +nav.toc select option { + text-align: center; +} + +nav.toc input { + display: block; + height: 2em; + width: 90%; + width: calc(100% - 5em); + margin: 1.2em auto; + padding: 0 1em; + border: 1px solid #c9c9c9; + border-radius: 1em; + font-size: .83em; +} + +nav.toc > ul * { + margin: 0; +} + +nav.toc ul { + color: #404040; + padding: 0; + list-style: none; +} + +nav.toc ul .toctext { + color: inherit; + display: block; +} + +nav.toc ul a:hover { + color: #fcfcfc; + background-color: #4e4a4a; +} + +nav.toc ul.internal a { + color: inherit; + display: block; +} + +nav.toc ul.internal a:hover { + background-color: #d6d6d6; +} + +nav.toc ul.internal { + background-color: #e3e3e3; + box-shadow: inset -14px 0px 5px -12px rgb(210,210,210); + list-style: none; +} + +nav.toc ul.internal li.toplevel { + border-top: 1px solid #c9c9c9; + font-weight: bold; +} + +nav.toc ul.internal li.toplevel:first-child { + border-top: none; +} + +nav.toc .toctext { + padding-top: 0.3em; + padding-bottom: 0.3em; + padding-right: 1em; +} + +nav.toc ul .toctext { + padding-left: 1em; +} + +nav.toc ul ul .toctext { + padding-left: 2em; +} + +nav.toc ul ul ul .toctext { + padding-left: 3em; +} + +nav.toc li.current > .toctext { + border-top: 1px solid #c9c9c9; + border-bottom: 1px solid #c9c9c9; + color: #404040; + font-weight: bold; + background-color: white; +} + +article { + margin-left: 20em; + min-width: 20em; + max-width: 48em; + padding: 2em; +} + +article > header {} + +article > header div#topbar { + display: none; +} + +article > header nav ul { + display: inline-block; + list-style: none; + margin: 0; + padding: 0; +} + +article > header nav li { + display: inline-block; + padding-right: 0.2em; +} + +article > header nav li:before { + content: "»"; + padding-right: 0.2em; +} + +article > header .edit-page { + float: right; +} + +article > footer {} + +article > footer a.prev { + float: left; +} +article > footer a.next { + float: right; +} + +article > footer a .direction:after { + content: ": "; +} + +article hr { + margin: 1em 0; +} + +article section.docstring { + border: 1px solid #ddd; + margin: 0.5em 0; + padding: 0.5em; + border-radius: 3px; +} + +article section.docstring .docstring-header { + margin-bottom: 1em; +} + +article section.docstring .docstring-binding { + color: #333; + font-weight: bold; +} + +article section.docstring .docstring-category { + font-style: italic; +} + +article section.docstring a.source-link { + display: block; + font-weight: bold; +} + +.nav-anchor, +.nav-anchor:hover, +.nav-anchor:visited { + color: #333; +} + +/* + * Admonitions + * + * Colors (title, body) + * warning: #f0b37e #ffedcc (orange) + * note: #6ab0de #e7f2fa (blue) + * tip: #1abc9c #dbfaf4 (green) +*/ +.admonition { + border-radius: 3px; + background-color: #eeeeee; +} + +.admonition-title { + border-radius: 3px 3px 0 0; + background-color: #9b9b9b; + padding: 0.15em 0.5em; +} + +.admonition-text { + padding: 0.5em; +} + +.admonition-text > :first-child { + margin-top: 0; +} + +.admonition-text > :last-child { + margin-bottom: 0; +} + +.admonition > .admonition-title:before { + font-family: "FontAwesome"; + margin-right: 5px; + content: "\f06a"; +} + +.admonition.warning > .admonition-title { + background-color: #f0b37e; +} + +.admonition.warning { + background-color: #ffedcc; +} + +.admonition.note > .admonition-title { + background-color: #6ab0de; +} + +.admonition.note { + background-color: #e7f2fa; +} + +.admonition.tip > .admonition-title { + background-color: #1abc9c; +} + +.admonition.tip { + background-color: #dbfaf4; +} + + +/* footnotes */ +.footnote { + padding-left: 0.8em; + border-left: 2px solid #ccc; +} + +/* Search page */ +#search-results .category { + font-size: smaller; +} + +#search-results .category:before { + content: " "; +} + +/* Overriding the block style of highligh.js. + * We have to override the padding and the background-color, since we style this + * part ourselves. Specifically, we style the
 surrounding the , while
+ * highlight.js applies the .hljs style directly to the  tag.
+ */
+.hljs {
+    background-color: transparent;
+    padding: 0;
+}
+
+@media only screen and (max-width: 768px) {
+    nav.toc {
+        position: fixed;
+        overflow-y: scroll;
+        width: 16em;
+        left: -16em;
+        -webkit-overflow-scrolling: touch;
+        -webkit-transition-property: left; /* Safari */
+        -webkit-transition-duration: 0.3s; /* Safari */
+        transition-property: left;
+        transition-duration: 0.3s;
+        -webkit-transition-timing-function: ease-out; /* Safari */
+        transition-timing-function: ease-out;
+        z-index: 2;
+    }
+
+    nav.toc.show {
+        left: 0;
+    }
+
+    article {
+        margin-left: 0;
+        padding: 3em 0.9em 0 0.9em; /* top right bottom left */
+        overflow-wrap: break-word;
+    }
+
+    article > header {
+        position: fixed;
+        left: 0;
+        z-index: 1;
+    }
+
+    article > header nav, hr {
+        display: none;
+    }
+
+    article > header div#topbar {
+        display: block; /* is mobile */
+        position: fixed;
+        width: 100%;
+        height: 1.5em;
+        padding-top: 1em;
+        padding-bottom: 1em;
+        background-color: #fcfcfc;
+        box-shadow: 0 1px 3px rgba(0,0,0,.26);
+        top: 0;
+        -webkit-transition-property: top; /* Safari */
+        -webkit-transition-duration: 0.3s; /* Safari */
+        transition-property: top;
+        transition-duration: 0.3s;
+    }
+
+    article > header div#topbar.headroom--unpinned.headroom--not-top.headroom--not-bottom {
+        top: -4em;
+        -webkit-transition-property: top; /* Safari */
+        -webkit-transition-duration: 0.7s; /* Safari */
+        transition-property: top;
+        transition-duration: 0.7s;
+    }
+
+    article > header div#topbar span {
+        position: fixed;
+        width: 80%;
+        height: 1.5em;
+        margin-top: -0.1em;
+        margin-left: 0.9em;
+        font-size: 1.2em;
+        overflow: hidden;
+    }
+
+    article > header div#topbar a.fa-bars {
+        float: right;
+        padding: 0.6em;
+        margin-top: -0.6em;
+        margin-right: 0.3em;
+        font-size: 1.5em;
+    }
+
+    article > header div#topbar a.fa-bars:visited {
+        color: #3091d1;
+    }
+
+    article table {
+        overflow-x: auto;
+        display: block;
+    }
+
+    article div.MathJax_Display {
+        overflow: scroll;
+    }
+
+    article span.MathJax {
+        overflow: hidden;
+    }
+}
+
+@media only screen and (max-width: 320px) {
+    body {
+        font-size: 15px;
+    }
+}
diff --git a/v0.2.3/assets/documenter.js b/v0.2.3/assets/documenter.js
new file mode 100644
index 0000000..5d31622
--- /dev/null
+++ b/v0.2.3/assets/documenter.js
@@ -0,0 +1,129 @@
+/*
+ * Part of Documenter.jl
+ *     https://github.com/JuliaDocs/Documenter.jl
+ *
+ * License: MIT
+ */
+
+requirejs.config({
+    paths: {
+        'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min',
+        'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.0/jquery-ui.min',
+        'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.9.3/headroom.min',
+        'mathjax': 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS_HTML',
+        'highlight': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min',
+        'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/languages/julia.min',
+        'highlight-julia-repl': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/languages/julia-repl.min',
+    },
+    shim: {
+        'mathjax' : {
+            exports: "MathJax"
+        },
+        'highlight-julia': ['highlight'],
+        'highlight-julia-repl': ['highlight'],
+    }
+});
+
+// Load MathJax
+require(['mathjax'], function(MathJax) {
+    MathJax.Hub.Config({
+      "tex2jax": {
+        inlineMath: [['$','$'], ['\\(','\\)']],
+        processEscapes: true
+      }
+    });
+    MathJax.Hub.Config({
+      config: ["MMLorHTML.js"],
+      jax: [
+        "input/TeX",
+        "output/HTML-CSS",
+        "output/NativeMML"
+      ],
+      extensions: [
+        "MathMenu.js",
+        "MathZoom.js",
+        "TeX/AMSmath.js",
+        "TeX/AMSsymbols.js",
+        "TeX/autobold.js",
+        "TeX/autoload-all.js"
+      ]
+    });
+    MathJax.Hub.Config({
+      TeX: { equationNumbers: { autoNumber: "AMS" } }
+    });
+})
+
+require(['jquery', 'highlight', 'highlight-julia', 'highlight-julia-repl'], function($, hljs) {
+    $(document).ready(function() {
+        hljs.initHighlighting();
+    })
+
+})
+
+// update the version selector with info from the siteinfo.js and ../versions.js files
+require(['jquery'], function($) {
+    $(document).ready(function() {
+        var version_selector = $("#version-selector");
+
+        // add the current version to the selector based on siteinfo.js, but only if the selector is empty
+        if (typeof DOCUMENTER_CURRENT_VERSION !== 'undefined' && $('#version-selector > option').length == 0) {
+            var option = $("");
+            version_selector.append(option);
+        }
+
+        if (typeof DOC_VERSIONS !== 'undefined') {
+            var existing_versions = $('#version-selector > option');
+            var existing_versions_texts = existing_versions.map(function(i,x){return x.text});
+            DOC_VERSIONS.forEach(function(each) {
+                var version_url = documenterBaseURL + "/../" + each;
+                var existing_id = $.inArray(each, existing_versions_texts);
+                // if not already in the version selector, add it as a new option,
+                // otherwise update the old option with the URL and enable it
+                if (existing_id == -1) {
+                    var option = $("");
+                    version_selector.append(option);
+                } else {
+                    var option = existing_versions[existing_id];
+                    option.value = version_url;
+                    option.disabled = false;
+                }
+            });
+        }
+
+        // only show the version selector if the selector has been populated
+        if ($('#version-selector > option').length > 0) {
+            version_selector.css("visibility", "visible");
+        }
+    })
+
+})
+
+// mobile
+require(['jquery', 'headroom'], function($, Headroom) {
+    $(document).ready(function() {
+        var navtoc = $("nav.toc");
+        $("nav.toc li.current a.toctext").click(function() {
+            navtoc.toggleClass('show');
+        });
+        $("article > header div#topbar a.fa-bars").click(function(ev) {
+            ev.preventDefault();
+            navtoc.toggleClass('show');
+            if (navtoc.hasClass('show')) {
+                var title = $("article > header div#topbar span").text();
+                $("nav.toc ul li a:contains('" + title + "')").focus();
+            }
+        });
+        $("article#docs").bind('click', function(ev) {
+            if ($(ev.target).is('div#topbar a.fa-bars')) {
+                return;
+            }
+            if (navtoc.hasClass('show')) {
+                navtoc.removeClass('show');
+            }
+        });
+        if ($("article > header div#topbar").css('display') == 'block') {
+            var headroom = new Headroom(document.querySelector("article > header div#topbar"), {"tolerance": {"up": 10, "down": 10}});
+            headroom.init();
+        }
+    })
+})
diff --git a/v0.2.3/assets/search.js b/v0.2.3/assets/search.js
new file mode 100644
index 0000000..5eb7fee
--- /dev/null
+++ b/v0.2.3/assets/search.js
@@ -0,0 +1,243 @@
+/*
+ * Part of Documenter.jl
+ *     https://github.com/JuliaDocs/Documenter.jl
+ *
+ * License: MIT
+ */
+
+// parseUri 1.2.2
+// (c) Steven Levithan 
+// MIT License
+function parseUri (str) {
+	var	o   = parseUri.options,
+		m   = o.parser[o.strictMode ? "strict" : "loose"].exec(str),
+		uri = {},
+		i   = 14;
+
+	while (i--) uri[o.key[i]] = m[i] || "";
+
+	uri[o.q.name] = {};
+	uri[o.key[12]].replace(o.q.parser, function ($0, $1, $2) {
+		if ($1) uri[o.q.name][$1] = $2;
+	});
+
+	return uri;
+};
+parseUri.options = {
+	strictMode: false,
+	key: ["source","protocol","authority","userInfo","user","password","host","port","relative","path","directory","file","query","anchor"],
+	q:   {
+		name:   "queryKey",
+		parser: /(?:^|&)([^&=]*)=?([^&]*)/g
+	},
+	parser: {
+		strict: /^(?:([^:\/?#]+):)?(?:\/\/((?:(([^:@]*)(?::([^:@]*))?)?@)?([^:\/?#]*)(?::(\d*))?))?((((?:[^?#\/]*\/)*)([^?#]*))(?:\?([^#]*))?(?:#(.*))?)/,
+		loose:  /^(?:(?![^:@]+:[^:@\/]*@)([^:\/?#.]+):)?(?:\/\/)?((?:(([^:@]*)(?::([^:@]*))?)?@)?([^:\/?#]*)(?::(\d*))?)(((\/(?:[^?#](?![^?#\/]*\.[^?#\/.]+(?:[?#]|$)))*\/?)?([^?#\/]*))(?:\?([^#]*))?(?:#(.*))?)/
+	}
+};
+
+requirejs.config({
+    paths: {
+        'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min',
+        'lunr': 'https://cdnjs.cloudflare.com/ajax/libs/lunr.js/2.1.3/lunr.min',
+        'lodash': 'https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.4/lodash.min',
+    }
+});
+
+var currentScript = document.currentScript;
+
+require(["jquery", "lunr", "lodash"], function($, lunr, _) {
+    $("#search-form").submit(function(e) {
+        e.preventDefault()
+    })
+
+    // list below is the lunr 2.1.3 list minus the intersect with names(Base)
+    // (all, any, get, in, is, which) and (do, else, for, let, where, while, with)
+    // ideally we'd just filter the original list but it's not available as a variable
+    lunr.stopWordFilter = lunr.generateStopWordFilter([
+        'a',
+        'able',
+        'about',
+        'across',
+        'after',
+        'almost',
+        'also',
+        'am',
+        'among',
+        'an',
+        'and',
+        'are',
+        'as',
+        'at',
+        'be',
+        'because',
+        'been',
+        'but',
+        'by',
+        'can',
+        'cannot',
+        'could',
+        'dear',
+        'did',
+        'does',
+        'either',
+        'ever',
+        'every',
+        'from',
+        'got',
+        'had',
+        'has',
+        'have',
+        'he',
+        'her',
+        'hers',
+        'him',
+        'his',
+        'how',
+        'however',
+        'i',
+        'if',
+        'into',
+        'it',
+        'its',
+        'just',
+        'least',
+        'like',
+        'likely',
+        'may',
+        'me',
+        'might',
+        'most',
+        'must',
+        'my',
+        'neither',
+        'no',
+        'nor',
+        'not',
+        'of',
+        'off',
+        'often',
+        'on',
+        'only',
+        'or',
+        'other',
+        'our',
+        'own',
+        'rather',
+        'said',
+        'say',
+        'says',
+        'she',
+        'should',
+        'since',
+        'so',
+        'some',
+        'than',
+        'that',
+        'the',
+        'their',
+        'them',
+        'then',
+        'there',
+        'these',
+        'they',
+        'this',
+        'tis',
+        'to',
+        'too',
+        'twas',
+        'us',
+        'wants',
+        'was',
+        'we',
+        'were',
+        'what',
+        'when',
+        'who',
+        'whom',
+        'why',
+        'will',
+        'would',
+        'yet',
+        'you',
+        'your'
+        ])
+
+    // add . as a separator, because otherwise "title": "Documenter.Anchors.add!"
+    // would not find anything if searching for "add!", only for the entire qualification
+    lunr.tokenizer.separator = /[\s\-\.]+/
+
+    // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names
+    lunr.trimmer = function (token) {
+        return token.update(function (s) {
+            return s.replace(/^[^a-zA-Z0-9@!]+/, '').replace(/[^a-zA-Z0-9@!]+$/, '')
+        })
+    }
+
+    lunr.Pipeline.registerFunction(lunr.stopWordFilter, 'juliaStopWordFilter')
+    lunr.Pipeline.registerFunction(lunr.trimmer, 'juliaTrimmer')
+
+    var index = lunr(function () {
+        this.ref('location')
+        this.field('title')
+        this.field('text')
+        documenterSearchIndex['docs'].forEach(function(e) {
+            this.add(e)
+        }, this)
+    })
+    var store = {}
+
+    documenterSearchIndex['docs'].forEach(function(e) {
+        store[e.location] = {title: e.title, category: e.category}
+    })
+
+    $(function(){
+        function update_search(querystring) {
+            tokens = lunr.tokenizer(querystring)
+            results = index.query(function (q) {
+                tokens.forEach(function (t) {
+                    q.term(t.toString(), {
+                        fields: ["title"],
+                        boost: 10,
+                        usePipeline: false,
+                        editDistance: 2,
+                        wildcard: lunr.Query.wildcard.NONE
+                    })
+                    q.term(t.toString(), {
+                        fields: ["text"],
+                        boost: 1,
+                        usePipeline: true,
+                        editDistance: 2,
+                        wildcard: lunr.Query.wildcard.NONE
+                    })
+                })
+            })
+            $('#search-info').text("Number of results: " + results.length)
+            $('#search-results').empty()
+            results.forEach(function(result) {
+                data = store[result.ref]
+                link = $('')
+                link.text(data.title)
+                link.attr('href', documenterBaseURL+'/'+result.ref)
+                cat = $('('+data.category+')')
+                li = $('
  • ').append(link).append(cat) + $('#search-results').append(li) + }) + } + + function update_search_box() { + querystring = $('#search-query').val() + update_search(querystring) + } + + $('#search-query').keyup(_.debounce(update_search_box, 250)) + $('#search-query').change(update_search_box) + + search_query_uri = parseUri(window.location).queryKey["q"] + if(search_query_uri !== undefined) { + search_query = decodeURIComponent(search_query_uri.replace(/\+/g, '%20')) + $("#search-query").val(search_query) + } + update_search_box(); + }) +}) diff --git a/v0.2.3/index.html b/v0.2.3/index.html new file mode 100644 index 0000000..d094248 --- /dev/null +++ b/v0.2.3/index.html @@ -0,0 +1,63 @@ + +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");
    +
    +julia> generate("MyPkg", t)
    +INFO: Initialized git repo at /tmp/tmpDAskPD/MyPkg
    +INFO: Made empty initial commit
    +INFO: Set remote origin to https://github.com/myusername/MyPkg.jl
    +INFO: Staged 6 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE
    +INFO: Committed files generated by PkgTemplates
    +INFO: Moved temporary package directory into /home/travis/.julia/v0.6/
    +INFO: Finished
    +
    +julia> run(`git -C $(joinpath(t.dir, "MyPkg")) ls-tree -r --name-only HEAD`)
    +.gitignore
    +LICENSE
    +README.md
    +REQUIRE
    +src/MyPkg.jl
    +test/runtests.jl

    However, we can also configure a number of keyword arguments to Template and generate:

    julia> using PkgTemplates
    +
    +julia> t = Template(;
    +           user="myusername",
    +           license="MIT",
    +           authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
    +           years="2016-2017",
    +           dir=joinpath(homedir(), "code"),
    +           julia_version=v"0.5.2",
    +           requirements=["PkgTemplates"],
    +           gitconfig=Dict("diff.renames" => true),
    +           plugins=[
    +               TravisCI(),
    +               CodeCov(),
    +               Coveralls(),
    +               AppVeyor(),
    +               GitHubPages(),
    +           ],
    +       );
    +
    +julia> generate("MyPkg", t; force=true, ssh=true)
    +INFO: Initialized git repo at /tmp/tmplyg8Ll/MyPkg
    +INFO: Applied git configuration
    +INFO: Made empty initial 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, .travis.yml, .appveyor.yml, docs/
    +INFO: Committed files generated by PkgTemplates
    +INFO: Moved temporary package directory into /home/travis/code/
    +INFO: Finished
    +WARNING: Remember to push all created branches to your remote: git push --all
    +
    +julia> run(`git -C $(joinpath(t.dir, "MyPkg")) ls-tree -r --name-only HEAD`)
    +.appveyor.yml
    +.gitignore
    +.travis.yml
    +LICENSE
    +README.md
    +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.

    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/v0.2.3/pages/index.html b/v0.2.3/pages/index.html new file mode 100644 index 0000000..1561cfe --- /dev/null +++ b/v0.2.3/pages/index.html @@ -0,0 +1,2 @@ + +Index · PkgTemplates.jl

    Index

    Index

    diff --git a/v0.2.3/pages/licenses.html b/v0.2.3/pages/licenses.html new file mode 100644 index 0000000..38b1af3 --- /dev/null +++ b/v0.2.3/pages/licenses.html @@ -0,0 +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([io::IO]) -> Void

    Print the names of all available licenses.

    source
    show_license([io::IO], license::AbstractString) -> Void

    Print the text of license. Errors if the license is not found.

    source

    Helper Functions

    read_license(license::AbstractString) -> String

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

    source
    diff --git a/v0.2.3/pages/package_generation.html b/v0.2.3/pages/package_generation.html new file mode 100644 index 0000000..15fe803 --- /dev/null +++ b/v0.2.3/pages/package_generation.html @@ -0,0 +1,38 @@ + +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

    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.

    • precompile::Bool=true: Whether or not to enable precompilation in generated packages.

    • julia_version::VersionNumber=VERSION: Minimum allowed Julia version.

    • requirements::Vector{<:AbstractString}=String[]: Package requirements. If there are duplicate requirements with different versions, i.e. ["PkgTemplates", "PkgTemplates 0.1"], an ArgumentError is thrown. Each entry in this array will be copied into the REQUIRE file of packages generated with this template.

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

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

    source
    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.generateFunction.
    generate(
    +    pkg_name::AbstractString,
    +    t::Template;
    +    force::Bool=false,
    +    ssh::Bool=false,
    +    backup_dir::AbstractString="",
    +) -> 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 (this keyword is mostly for internal usage).

    Notes

    The package is generated entirely in a temporary directory and only moved into joinpath(t.dir, pkg_name) at the very end. In the case of an error, the temporary directory will contain leftovers, but the destination directory will remain untouched (this is especially helpful when force=true).

    source
    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(
    +    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(
    +    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(
    +    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(
    +    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(
    +    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(
    +    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
    diff --git a/v0.2.3/pages/plugin_development.html b/v0.2.3/pages/plugin_development.html new file mode 100644 index 0000000..9edd381 --- /dev/null +++ b/v0.2.3/pages/plugin_development.html @@ -0,0 +1,91 @@ + +Plugin Development · PkgTemplates.jl

    Plugin Development

    Plugin Development

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

    A plugin to be added to a Template, which adds some functionality or integration. New plugins should almost always extend GenericPlugin or CustomPlugin.

    source

    Generic Plugins

    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
    +    badges::Vector{Badge}
    +    view::Dict{String, Any}
    +
    +    function MyPlugin(; config_file::Union{AbstractString, Void}="")
    +        if config_file != nothing
    +            config_file = if isempty(config_file)
    +                joinpath(DEFAULTS_DIR, "my-plugin.toml")
    +            elseif isfile(config_file)
    +                abspath(config_file)
    +            else
    +                throw(ArgumentError(
    +                    "File $(abspath(config_file)) does not exist"
    +                ))
    +            end
    +        end
    +        new(
    +            ["*.mgp"],
    +            config_file,
    +            ".my-plugin.toml",
    +            [
    +                Badge(
    +                    "My Plugin",
    +                    "https://myplugin.com/badge-{{YEAR}}.png",
    +                    "https://myplugin.com/{{USER}}/{{PKGNAME}}.jl",
    +                ),
    +            ],
    +            Dict{String, Any}("YEAR" => Dates.year(Dates.today())),
    +        )
    +    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

    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
    +
    +    MyPlugin() = new([], rand() > 0.8)
    +
    +    function gen_plugin(
    +        plugin::MyPlugin,
    +        template::Template,
    +        dir::AbstractString,
    +        pkg_name::AbstractString,
    +    )
    +        if plugin.lucky
    +            text = substitute(
    +                "You got lucky with {{PKGNAME}}, {{USER}}!",
    +                template,
    +            )
    +            gen_file(joinpath(dir, pkg_name, ".myplugin.yml"), text)
    +        else
    +            println("Maybe next time.")
    +        end
    +    end
    +
    +    function badges(
    +        plugin::MyPlugin,
    +        user::AbstractString,
    +        pkg_name::AbstractString,
    +    )
    +        if plugin.lucky
    +            return [
    +                format(Badge(
    +                    "You got lucky!",
    +                    "https://myplugin.com/badge.png",
    +                    "https://myplugin.com/$user/$pkg_name.jl",
    +                )),
    +            ]
    +        else
    +            return String[]
    +        end
    +    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

    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
    interactive(
    +    plugin_type::Type{<: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.badgesFunction.
    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_fileFunction.
    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

    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

    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.formatFunction.
    format(b::Badge)

    Return badge's data formatted as a Markdown string.

    source

    version_floor

    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/v0.2.3/pages/plugins.html b/v0.2.3/pages/plugins.html new file mode 100644 index 0000000..c1aeb02 --- /dev/null +++ b/v0.2.3/pages/plugins.html @@ -0,0 +1,2 @@ + +Plugins · PkgTemplates.jl

    Plugins

    Plugins

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

    Continuous Integration (CI)

    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(; 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(; 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

    Code Coverage

    CodeCov(; config_file::Union{AbstractString, Void}=nothing) -> CodeCov

    Add CodeCov to a template's plugins to optionally add a .codecov.yml configuration file to generated repositories, and an appropriate badge to the README. Also updates the .gitignore accordingly.

    Keyword Arguments:

    • config_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.

    source
    Coveralls(; config_file::Union{AbstractString, Void}=nothing) -> 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

    Documentation

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

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

    source
    diff --git a/v0.2.3/search.html b/v0.2.3/search.html new file mode 100644 index 0000000..62cb5c0 --- /dev/null +++ b/v0.2.3/search.html @@ -0,0 +1,2 @@ + +Search · PkgTemplates.jl

    Search

    Search

    Number of results: loading...

      diff --git a/v0.2.3/search_index.js b/v0.2.3/search_index.js new file mode 100644 index 0000000..fc7fcbe --- /dev/null +++ b/v0.2.3/search_index.js @@ -0,0 +1,515 @@ +var documenterSearchIndex = {"docs": [ + +{ + "location": "index.html#", + "page": "Home", + "title": "Home", + "category": "page", + "text": "" +}, + +{ + "location": "index.html#PkgTemplates-1", + "page": "Home", + "title": "PkgTemplates", + "category": "section", + "text": "(Image: Stable) (Image: Latest) (Image: Build Status) (Image: Build Status) (Image: CodeCov)PkgTemplates is a Julia package for creating new Julia packages in an easy, repeatable, and customizable way." +}, + +{ + "location": "index.html#Installation-1", + "page": "Home", + "title": "Installation", + "category": "section", + "text": "PkgTemplates is registered in METADATA.jl, so run Pkg.add(\"PkgTemplates\") for the latest release, or Pkg.clone(\"PkgTemplates\") for the development version." +}, + +{ + "location": "index.html#Usage-1", + "page": "Home", + "title": "Usage", + "category": "section", + "text": "The simplest template only requires your GitHub username.using PkgTemplates\nt = Template(; user=\"myusername\");\ngenerate(\"MyPkg\", t)\nrun(`git -C $(joinpath(t.dir, \"MyPkg\")) 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(),\n Coveralls(),\n AppVeyor(),\n GitHubPages(),\n ],\n);\ngenerate(\"MyPkg\", t; force=true, ssh=true)\nrun(`git -C $(joinpath(t.dir, \"MyPkg\")) 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." +}, + +{ + "location": "index.html#Comparison-to-[PkgDev](https://github.com/JuliaLang/PkgDev.jl)-1", + "page": "Home", + "title": "Comparison to PkgDev", + "category": "section", + "text": "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." +}, + +{ + "location": "pages/package_generation.html#", + "page": "Package Generation", + "title": "Package Generation", + "category": "page", + "text": "CurrentModule = PkgTemplates" +}, + +{ + "location": "pages/package_generation.html#Package-Generation-1", + "page": "Package Generation", + "title": "Package Generation", + "category": "section", + "text": "Creating new packages with PkgTemplates revolves around creating a new Template, then calling generate on it." +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.Template", + "page": "Package Generation", + "title": "PkgTemplates.Template", + "category": "Type", + "text": "Template(; kwargs...) -> Template\n\nRecords common information used to generate a package. If you don't wish to manually create a template, you can use interactive_template instead.\n\nKeyword Arguments\n\nuser::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.\nhost::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.\nlicense::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.\nauthors::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.\nyears::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\".\ndir::AbstractString=Pkg.dir(): Directory in which the package will go. Relative paths are converted to absolute ones at template creation time.\nprecompile::Bool=true: Whether or not to enable precompilation in generated packages.\njulia_version::VersionNumber=VERSION: Minimum allowed Julia version.\nrequirements::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.\ngitconfig::Dict=Dict(): Git configuration options.\nplugins::Vector{<:Plugin}=Plugin[]: A list of Plugins that the package will include.\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.interactive_template", + "page": "Package Generation", + "title": "PkgTemplates.interactive_template", + "category": "Function", + "text": "interactive_template(; fast::Bool=false) -> Template\n\nInteractively create a Template. If fast is set, defaults will be assumed for all values except username and plugins.\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#Template-1", + "page": "Package Generation", + "title": "Template", + "category": "section", + "text": "Template\ninteractive_template" +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.generate", + "page": "Package Generation", + "title": "PkgTemplates.generate", + "category": "Function", + "text": "generate(\n pkg_name::AbstractString,\n t::Template;\n force::Bool=false,\n ssh::Bool=false,\n backup_dir::AbstractString=\"\",\n) -> Void\n\nGenerate a package named pkg_name from template.\n\nKeyword Arguments\n\nforce::Bool=false: Whether or not to overwrite old packages with the same name.\nssh::Bool=false: Whether or not to use SSH for the remote.\nbackup_dir::AbstractString=\"\": Directory in which to store the generated package if t.dir is not a valid directory. If left unset, a temporary directory will be created (this keyword is mostly for internal usage).\n\nNotes\n\nThe 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).\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.generate_interactive", + "page": "Package Generation", + "title": "PkgTemplates.generate_interactive", + "category": "Function", + "text": "generate_interactive(\n pkg_name::AbstractString;\n force::Bool=false,\n ssh::Bool=false,\n backup_dir::AbstractString=\"\",\n fast::Bool=false,\n) -> Void\n\nInteractively 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.\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#generate-1", + "page": "Package Generation", + "title": "generate", + "category": "section", + "text": "generate\ngenerate_interactive" +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.gen_entrypoint", + "page": "Package Generation", + "title": "PkgTemplates.gen_entrypoint", + "category": "Function", + "text": "gen_entrypoint(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate the module entrypoint in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose entrypoint we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.gen_tests", + "page": "Package Generation", + "title": "PkgTemplates.gen_tests", + "category": "Function", + "text": "gen_tests(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate the test directory and entrypoint in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose tests we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.gen_require", + "page": "Package Generation", + "title": "PkgTemplates.gen_require", + "category": "Function", + "text": "gen_require(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate the REQUIRE file in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose REQUIRE we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.gen_readme", + "page": "Package Generation", + "title": "PkgTemplates.gen_readme", + "category": "Function", + "text": "gen_readme(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate a README in the temp package directory with badges for each enabled plugin.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose README we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.gen_gitignore", + "page": "Package Generation", + "title": "PkgTemplates.gen_gitignore", + "category": "Function", + "text": "gen_gitignore(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate a .gitignore in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose .gitignore we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#PkgTemplates.gen_license", + "page": "Package Generation", + "title": "PkgTemplates.gen_license", + "category": "Function", + "text": "gen_license(\n dir::AbstractString,\n pkg_name::AbstractString,\n template::Template,\n) -> Vector{String}\n\nCreate a license in the temp package directory.\n\nArguments\n\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\ntemplate::Template: The template whose LICENSE we are generating.\n\nReturns an array of generated file/directory names.\n\n\n\n" +}, + +{ + "location": "pages/package_generation.html#Helper-Functions-1", + "page": "Package Generation", + "title": "Helper Functions", + "category": "section", + "text": "gen_entrypoint\ngen_tests\ngen_require\ngen_readme\ngen_gitignore\ngen_license" +}, + +{ + "location": "pages/plugins.html#", + "page": "Plugins", + "title": "Plugins", + "category": "page", + "text": "CurrentModule = PkgTemplates" +}, + +{ + "location": "pages/plugins.html#Plugins-1", + "page": "Plugins", + "title": "Plugins", + "category": "section", + "text": "Plugins are the secret sauce behing PkgTemplates's customization and extension. This page describes plugins that already exist; for information on writing your own plugins, see Plugin Development." +}, + +{ + "location": "pages/plugins.html#PkgTemplates.TravisCI", + "page": "Plugins", + "title": "PkgTemplates.TravisCI", + "category": "Type", + "text": "TravisCI(; config_file::Union{AbstractString, Void}=\"\") -> TravisCI\n\nAdd TravisCI to a template's plugins to add a .travis.yml configuration file to generated repositories, and an appropriate badge to the README.\n\nKeyword Arguments:\n\nconfig_file::Union{AbstractString, Void}=\"\": Path to a custom .travis.yml. If nothing is supplied, no file will be generated.\n\n\n\n" +}, + +{ + "location": "pages/plugins.html#PkgTemplates.AppVeyor", + "page": "Plugins", + "title": "PkgTemplates.AppVeyor", + "category": "Type", + "text": "AppVeyor(; config_file::Union{AbstractString, Void}=\"\") -> AppVeyor\n\nAdd AppVeyor to a template's plugins to add a .appveyor.yml configuration file to generated repositories, and an appropriate badge to the README.\n\nKeyword Arguments\n\nconfig_file::Union{AbstractString, Void}=\"\": Path to a custom .appveyor.yml. If nothing is supplied, no file will be generated.\n\n\n\n" +}, + +{ + "location": "pages/plugins.html#PkgTemplates.GitLabCI", + "page": "Plugins", + "title": "PkgTemplates.GitLabCI", + "category": "Type", + "text": "GitLabCI(; config_file::Union{AbstractString, Void}=\"\", coverage::Bool=true) -> GitLabCI\n\nAdd GitLabCI to a template's plugins to add a .gitlab-ci.yml configuration file to generated repositories, and appropriate badge(s) to the README.\n\nKeyword Arguments:\n\nconfig_file::Union{AbstractString, Void}=\"\": Path to a custom .gitlab-ci.yml. If nothing is supplied, no file will be generated.\ncoverage::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+)%.\n\n\n\n" +}, + +{ + "location": "pages/plugins.html#Continuous-Integration-(CI)-1", + "page": "Plugins", + "title": "Continuous Integration (CI)", + "category": "section", + "text": "TravisCI\nAppVeyor\nGitLabCI" +}, + +{ + "location": "pages/plugins.html#PkgTemplates.CodeCov", + "page": "Plugins", + "title": "PkgTemplates.CodeCov", + "category": "Type", + "text": "CodeCov(; config_file::Union{AbstractString, Void}=nothing) -> CodeCov\n\nAdd 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.\n\nKeyword Arguments:\n\nconfig_file::Union{AbstractString, Void}=nothing: Path to a custom .codecov.yml. If left unset, no file will be generated.\n\n\n\n" +}, + +{ + "location": "pages/plugins.html#PkgTemplates.Coveralls", + "page": "Plugins", + "title": "PkgTemplates.Coveralls", + "category": "Type", + "text": "Coveralls(; config_file::Union{AbstractString, Void}=nothing) -> Coveralls\n\nAdd 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.\n\nKeyword Arguments:\n\nconfig_file::Union{AbstractString, Void}=nothing: Path to a custom .coveralls.yml. If left unset, no file will be generated.\n\n\n\n" +}, + +{ + "location": "pages/plugins.html#Code-Coverage-1", + "page": "Plugins", + "title": "Code Coverage", + "category": "section", + "text": "CodeCov\nCoveralls" +}, + +{ + "location": "pages/plugins.html#PkgTemplates.Documenter", + "page": "Plugins", + "title": "PkgTemplates.Documenter", + "category": "Type", + "text": "Add a Documenter subtype to a template's plugins to add support for documentation generation via Documenter.jl.\n\n\n\n" +}, + +{ + "location": "pages/plugins.html#PkgTemplates.GitHubPages", + "page": "Plugins", + "title": "PkgTemplates.GitHubPages", + "category": "Type", + "text": "GitHubPages(; assets::Vector{<:AbstractString}=String[]) -> GitHubPages\n\nAdd 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.\n\nKeyword Arguments\n\nassets::Vector{<:AbstractString}=String[]: Array of paths to Documenter asset files.\n\n\n\n" +}, + +{ + "location": "pages/plugins.html#Documentation-1", + "page": "Plugins", + "title": "Documentation", + "category": "section", + "text": "Documenter\nGitHubPages" +}, + +{ + "location": "pages/plugin_development.html#", + "page": "Plugin Development", + "title": "Plugin Development", + "category": "page", + "text": "CurrentModule = PkgTemplates" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.Plugin", + "page": "Plugin Development", + "title": "PkgTemplates.Plugin", + "category": "Type", + "text": "A plugin to be added to a Template, which adds some functionality or integration. New plugins should almost always extend GenericPlugin or CustomPlugin.\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#Plugin-Development-1", + "page": "Plugin Development", + "title": "Plugin Development", + "category": "section", + "text": "The best and easiest way to contribute to PkgTemplates is to write new plugins.Plugin" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.GenericPlugin", + "page": "Plugin Development", + "title": "PkgTemplates.GenericPlugin", + "category": "Type", + "text": "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.\n\nAttributes\n\ngitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.\nsrc::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\").\ndest::AbstractString: Path to the generated file, relative to the root of the generated package repository.\nbadges::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.\nview::Dict{String, Any}: Additional substitutions to make in both the plugin's badges and its associated file. See substitute for details.\n\nExample\n\n@auto_hash_equals struct MyPlugin <: GenericPlugin\n gitignore::Vector{AbstractString}\n src::Nullable{AbstractString}\n dest::AbstractString\n badges::Vector{Badge}\n view::Dict{String, Any}\n\n function MyPlugin(; config_file::Union{AbstractString, Void}=\"\")\n if config_file != nothing\n config_file = if isempty(config_file)\n joinpath(DEFAULTS_DIR, \"my-plugin.toml\")\n elseif isfile(config_file)\n abspath(config_file)\n else\n throw(ArgumentError(\n \"File $(abspath(config_file)) does not exist\"\n ))\n end\n end\n new(\n [\"*.mgp\"],\n config_file,\n \".my-plugin.toml\",\n [\n Badge(\n \"My Plugin\",\n \"https://myplugin.com/badge-{{YEAR}}.png\",\n \"https://myplugin.com/{{USER}}/{{PKGNAME}}.jl\",\n ),\n ],\n Dict{String, Any}(\"YEAR\" => Dates.year(Dates.today())),\n )\n end\nend\n\ninteractive(plugin_type::Type{MyPlugin}) = interactive(plugin_type; file=\"my-plugin.toml\")\n\nThe 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.\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#Generic-Plugins-1", + "page": "Plugin Development", + "title": "Generic Plugins", + "category": "section", + "text": "GenericPlugin" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.CustomPlugin", + "page": "Plugin Development", + "title": "PkgTemplates.CustomPlugin", + "category": "Type", + "text": "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.\n\nAttributes\n\ngitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.\n\nExample\n\n@auto_hash_equals struct MyPlugin <: CustomPlugin\n gitignore::Vector{AbstractString}\n lucky::Bool\n\n MyPlugin() = new([], rand() > 0.8)\n\n function gen_plugin(\n plugin::MyPlugin,\n template::Template,\n dir::AbstractString,\n pkg_name::AbstractString,\n )\n if plugin.lucky\n text = substitute(\n \"You got lucky with {{PKGNAME}}, {{USER}}!\",\n template,\n )\n gen_file(joinpath(dir, pkg_name, \".myplugin.yml\"), text)\n else\n println(\"Maybe next time.\")\n end\n end\n\n function badges(\n plugin::MyPlugin,\n user::AbstractString,\n pkg_name::AbstractString,\n )\n if plugin.lucky\n return [\n format(Badge(\n \"You got lucky!\",\n \"https://myplugin.com/badge.png\",\n \"https://myplugin.com/$user/$pkg_name.jl\",\n )),\n ]\n else\n return String[]\n end\n end\nend\n\ninteractive(plugin_type::Type{MyPlugin}) = MyPlugin()\n\nThis plugin doesn't do much, but it demonstrates how gen_plugin, badges and interactive can be implemented using substitute, gen_file, Badge, and format.\n\nDefining Template Files\n\nOften, 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.\n\nNote: Due to a bug in Mustache, conditionals can insert undesired newlines (more detail here).\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#Custom-Plugins-1", + "page": "Plugin Development", + "title": "Custom Plugins", + "category": "section", + "text": "CustomPlugin" +}, + +{ + "location": "pages/plugin_development.html#CustomPlugin-Required-Methods-1", + "page": "Plugin Development", + "title": "CustomPlugin Required Methods", + "category": "section", + "text": "" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.gen_plugin", + "page": "Plugin Development", + "title": "PkgTemplates.gen_plugin", + "category": "Function", + "text": "gen_plugin(\n plugin::Plugin,\n template::Template,\n dir::AbstractString,\n pkg_name::AbstractString\n) -> Vector{String}\n\nGenerate any files associated with a plugin.\n\nArguments\n\nplugin::Plugin: Plugin whose files are being generated.\ntemplate::Template: Template configuration.\ndir::AbstractString: The directory in which the files will be generated. Note that this will be joined to pkg_name.\npkg_name::AbstractString: Name of the package.\n\nReturns an array of generated file/directory names.\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.interactive", + "page": "Plugin Development", + "title": "PkgTemplates.interactive", + "category": "Function", + "text": "interactive(\n plugin_type::Type{<:Plugin};\n file::Union{AbstractString, Void}=\"\",\n) -> Plugin\n\nInteractively 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\").\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#gen_plugin-1", + "page": "Plugin Development", + "title": "gen_plugin", + "category": "section", + "text": "gen_plugin\ninteractiveNote: interactive is not strictly required, however without it, your custom plugin will not be available when creating templates with interactive_template." +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.badges", + "page": "Plugin Development", + "title": "PkgTemplates.badges", + "category": "Function", + "text": "badges(plugin::Plugin, user::AbstractString, pkg_name::AbstractString) -> Vector{String}\n\nGenerate Markdown badges for the plugin.\n\nArguments\n\nplugin::Plugin: Plugin whose badges we are generating.\nuser::AbstractString: Username of the package creator.\npkg_name::AbstractString: Name of the package.\n\nReturns an array of Markdown badges.\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#badges-1", + "page": "Plugin Development", + "title": "badges", + "category": "section", + "text": "badges" +}, + +{ + "location": "pages/plugin_development.html#Helper-Types/Functions-1", + "page": "Plugin Development", + "title": "Helper Types/Functions", + "category": "section", + "text": "" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.gen_file", + "page": "Plugin Development", + "title": "PkgTemplates.gen_file", + "category": "Function", + "text": "gen_file(file_path::AbstractString, text::AbstractString) -> Int\n\nCreate a new file containing some given text. Always ends the file with a newline.\n\nArguments\n\nfile::AbstractString: Path to the file to be created.\ntext::AbstractString: Text to write to the file.\n\nReturns the number of bytes written to the file.\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#gen_file-1", + "page": "Plugin Development", + "title": "gen_file", + "category": "section", + "text": "gen_file" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.substitute", + "page": "Plugin Development", + "title": "PkgTemplates.substitute", + "category": "Function", + "text": "substitute(template::AbstractString, view::Dict{String, Any}) -> String\n\nReplace placeholders in template with values in view via Mustache. template is not modified.\n\nFor information on how to structure template, see \"Defining Template Files\" section in Custom Plugins.\n\nNote: Conditionals in template without a corresponding key in view won't error, but will simply be evaluated as false.\n\n\n\nsubstitute(\n template::AbstractString,\n pkg_template::Template;\n view::Dict{String, Any}=Dict{String, Any}(),\n) -> String\n\nReplace placeholders in template, using some default replacements based on the pkg_template and additional ones in view. template is not modified.\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#substitute-1", + "page": "Plugin Development", + "title": "substitute", + "category": "section", + "text": "substitute" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.Badge", + "page": "Plugin Development", + "title": "PkgTemplates.Badge", + "category": "Type", + "text": "Badge(hover::AbstractString, image::AbstractString, link::AbstractString) -> Badge\n\nA Badge contains the data necessary to generate a Markdown badge.\n\nArguments\n\nhover::AbstractString: Text to appear when the mouse is hovered over the badge.\nimage::AbstractString: URL to the image to display.\nlink::AbstractString: URL to go to upon clicking the badge.\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#Badge-1", + "page": "Plugin Development", + "title": "Badge", + "category": "section", + "text": "Badge" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.format", + "page": "Plugin Development", + "title": "PkgTemplates.format", + "category": "Function", + "text": "format(b::Badge)\n\nReturn badge's data formatted as a Markdown string.\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#format-1", + "page": "Plugin Development", + "title": "format", + "category": "section", + "text": "format" +}, + +{ + "location": "pages/plugin_development.html#PkgTemplates.version_floor", + "page": "Plugin Development", + "title": "PkgTemplates.version_floor", + "category": "Function", + "text": "version_floor(v::VersionNumber=VERSION) -> String\n\nFormat the given Julia version.\n\nKeyword arguments\n\nv::VersionNumber=VERSION: Version to floor.\n\nReturns \"major.minor\" for the most recent release version relative to v. For prereleases with v.minor == v.patch == 0, returns \"major.minor-\".\n\n\n\n" +}, + +{ + "location": "pages/plugin_development.html#version_floor-1", + "page": "Plugin Development", + "title": "version_floor", + "category": "section", + "text": "version_floor" +}, + +{ + "location": "pages/licenses.html#", + "page": "Licenses", + "title": "Licenses", + "category": "page", + "text": "CurrentModule = PkgTemplates" +}, + +{ + "location": "pages/licenses.html#PkgTemplates.available_licenses", + "page": "Licenses", + "title": "PkgTemplates.available_licenses", + "category": "Function", + "text": "available_licenses([io::IO]) -> Void\n\nPrint the names of all available licenses.\n\n\n\n" +}, + +{ + "location": "pages/licenses.html#PkgTemplates.show_license", + "page": "Licenses", + "title": "PkgTemplates.show_license", + "category": "Function", + "text": "show_license([io::IO], license::AbstractString) -> Void\n\nPrint the text of license. Errors if the license is not found.\n\n\n\n" +}, + +{ + "location": "pages/licenses.html#Licenses-1", + "page": "Licenses", + "title": "Licenses", + "category": "section", + "text": "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\nshow_license" +}, + +{ + "location": "pages/licenses.html#PkgTemplates.read_license", + "page": "Licenses", + "title": "PkgTemplates.read_license", + "category": "Function", + "text": "read_license(license::AbstractString) -> String\n\nReturns the contents of license. Errors if the license is not found. Use available_licenses to view available licenses.\n\n\n\n" +}, + +{ + "location": "pages/licenses.html#Helper-Functions-1", + "page": "Licenses", + "title": "Helper Functions", + "category": "section", + "text": "read_license" +}, + +{ + "location": "pages/index.html#", + "page": "Index", + "title": "Index", + "category": "page", + "text": "" +}, + +{ + "location": "pages/index.html#Index-1", + "page": "Index", + "title": "Index", + "category": "section", + "text": "" +}, + +]} diff --git a/v0.2.3/siteinfo.js b/v0.2.3/siteinfo.js new file mode 100644 index 0000000..488dce7 --- /dev/null +++ b/v0.2.3/siteinfo.js @@ -0,0 +1 @@ +var DOCUMENTER_CURRENT_VERSION = "v0.2.3"; diff --git a/versions.js b/versions.js index 2892500..ce91ffb 100644 --- a/versions.js +++ b/versions.js @@ -3,6 +3,7 @@ var DOC_VERSIONS = [ "latest", "release-0.2", "release-0.1", + "v0.2.3", "v0.2.2", "v0.2.1", "v0.2.0",