diff --git a/Manifest.toml b/Manifest.toml index bffdf4c..e908460 100644 --- a/Manifest.toml +++ b/Manifest.toml @@ -4,9 +4,9 @@ uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f" [[DataAPI]] -git-tree-sha1 = "8903f0219d3472543fc4b2f5ebaf675a07f817c0" +git-tree-sha1 = "674b67f344687a88310213ddfa8a2b3c76cc4252" uuid = "9a962f9c-6df0-11e9-0e5d-c546b8b5ee8a" -version = "1.0.1" +version = "1.1.0" [[DataValueInterfaces]] git-tree-sha1 = "bfc1187b79289637fa0ef6d4436ebdfe6905cbd6" diff --git a/docs/src/developer.md b/docs/src/developer.md index a049b15..16e7c6a 100644 --- a/docs/src/developer.md +++ b/docs/src/developer.md @@ -91,7 +91,7 @@ badges(::Documenter) = [ Badge( "Dev", "https://img.shields.io/badge/docs-dev-blue.svg", - "https://{{{}USER}}.github.io/{{{PKG}}}.jl/dev", + "https://{{{USER}}}.github.io/{{{PKG}}}.jl/dev", ), ] diff --git a/src/plugin.jl b/src/plugin.jl index 00fddc9..a9f12f8 100644 --- a/src/plugin.jl +++ b/src/plugin.jl @@ -9,7 +9,8 @@ abstract type BasicPlugin <: Plugin end """ default_file(paths::AbstractString...) -> String -Return a path relative to the default template file directory (`$(contractuser(TEMPLATES_DIR))`). +Return a path relative to the default template file directory +(`$(contractuser(TEMPLATES_DIR))`). """ default_file(paths::AbstractString...) = joinpath(TEMPLATES_DIR, paths...) @@ -19,8 +20,10 @@ default_file(paths::AbstractString...) = joinpath(TEMPLATES_DIR, paths...) Return the view to be passed to the text templating engine for this plugin. `pkg` is the name of the package being generated. -For [`BasicPlugin`](@ref)s, this is used for both the plugin badges (see [`badges`](@ref)) and the template file (see [`source`](@ref)). -For other [`Plugin`](@ref)s, it is used only for badges, but you can always call it yourself as part of your [`hook`](@ref) implementation. +For [`BasicPlugin`](@ref)s, this is used for both the plugin badges +(see [`badges`](@ref)) and the template file (see [`source`](@ref)). +For other [`Plugin`](@ref)s, it is used only for badges, +but you can always call it yourself as part of your [`hook`](@ref) implementation. By default, an empty `Dict` is returned. """ @@ -31,7 +34,8 @@ view(::Plugin, ::Template, ::AbstractString) = Dict{String, Any}() The same as [`view`](@ref), but for use by package *users* for extension. -Values returned by this function will override those from [`view`](@ref) when the keys are the same. +Values returned by this function will override those from [`view`](@ref) +when the keys are the same. """ user_view(::Plugin, ::Template, ::AbstractString) = Dict{String, Any}() @@ -39,7 +43,9 @@ user_view(::Plugin, ::Template, ::AbstractString) = Dict{String, Any}() combined_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any} This function combines [`view`](@ref) and [`user_view`](@ref) for use in text templating. -If you're doing manual file creation or text templating (i.e. writing [`Plugin`](@ref)s that are not [`BasicPlugin`](@ref)s), then you should use this function rather than either of the former two. +If you're doing manual file creation or text templating (i.e. writing [`Plugin`](@ref)s +that are not [`BasicPlugin`](@ref)s), then you should use this function +rather than either of the former two. !!! note Do not implement this function yourself! @@ -66,7 +72,8 @@ tags(::Plugin) = "{{", "}}" Determines the order in which plugins are processed (higher goes first). The default priority (`DEFAULT_PRIORITY`), is `$DEFAULT_PRIORITY`. -You can implement this function per-stage (by using `::typeof(hook)`, for example), or for all stages by simply using `::Function`. +You can implement this function per-stage (by using `::typeof(hook)`, for example), +or for all stages by simply using `::Function`. """ priority(::Plugin, ::Function) = DEFAULT_PRIORITY @@ -112,12 +119,13 @@ function destination end Badge(hover::AbstractString, image::AbstractString, link::AbstractString) Container for Markdown badge data. -Each argument can contain placeholders (which will be filled in with values from [`combined_view`](@ref)). +Each argument can contain placeholders, +which will be filled in with values from [`combined_view`](@ref). ## 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. +- `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. """ struct Badge hover::String @@ -139,7 +147,9 @@ end Perform any required validation for a [`Plugin`](@ref). -It is preferred to do validation here instead of in [`prehook`](@ref), because this function is called at [`Template`](@ref) construction time, whereas the prehook is only run at package generation time. +It is preferred to do validation here instead of in [`prehook`](@ref), +because this function is called at [`Template`](@ref) construction time, +whereas the prehook is only run at package generation time. """ validate(::Plugin, ::Template) = nothing @@ -147,7 +157,8 @@ validate(::Plugin, ::Template) = nothing prehook(::Plugin, ::Template, pkg_dir::AbstractString) Stage 1 of the package generation process (the "before" stage, in general). -At this point, `pkg_dir` is an empty directory that will eventually contain the package, and neither the [`hook`](@ref)s nor the [`posthook`](@ref)s have run. +At this point, `pkg_dir` is an empty directory that will eventually contain the package, +and neither the [`hook`](@ref)s nor the [`posthook`](@ref)s have run. !!! note `pkg_dir` only stays empty until the first plugin chooses to create a file. @@ -161,11 +172,13 @@ prehook(::Plugin, ::Template, ::AbstractString) = nothing Stage 2 of the package generation pipeline (the "main" stage, in general). At this point, the [`prehook`](@ref)s have run, but not the [`posthook`](@ref)s. -`pkg_dir` is the directory in which the package is being generated (so `basename(pkg_dir)` is the package name). +`pkg_dir` is the directory in which the package is being generated +(so `basename(pkg_dir)` is the package name). !!! note You usually shouldn't implement this function for [`BasicPlugin`](@ref)s. - If you do, it should probably `invoke` the generic method (otherwise, there's not much reason to subtype `BasicPlugin`). + If you do, it should probably `invoke` the generic method + (otherwise, there's not much reason to subtype `BasicPlugin`). """ hook(::Plugin, ::Template, ::AbstractString) = nothing @@ -211,7 +224,8 @@ end render_file(file::AbstractString view::Dict{<:AbstractString}, tags) -> String Render a template file with the data in `view`. -`tags` should be a tuple of two strings, which are the opening and closing delimiters, or `nothing` to use the default delimiters. +`tags` should be a tuple of two strings, which are the opening and closing delimiters, +or `nothing` to use the default delimiters. """ function render_file(file::AbstractString, view::Dict{<:AbstractString}, tags) return render_text(read(file, String), view, tags) @@ -221,7 +235,8 @@ end render_text(text::AbstractString, view::Dict{<:AbstractString}, tags=nothing) -> String Render some text with the data in `view`. -`tags` should be a tuple of two strings, which are the opening and closing delimiters, or `nothing` to use the default delimiters. +`tags` should be a tuple of two strings, which are the opening and closing delimiters, +or `nothing` to use the default delimiters. """ function render_text(text::AbstractString, view::Dict{<:AbstractString}, tags=nothing) return tags === nothing ? render(text, view) : render(text, view; tags=tags) @@ -231,7 +246,8 @@ end needs_username(::Plugin) -> Bool Determine whether or not a plugin needs a Git hosting service username to function correctly. -If you are implementing a plugin that uses the `user` field of a [`Template`](@ref), you should implement this function and return `true`. +If you are implementing a plugin that uses the `user` field of a [`Template`](@ref), +you should implement this function and return `true`. """ needs_username(::Plugin) = false diff --git a/src/plugins/ci.jl b/src/plugins/ci.jl index 1ede621..531e306 100644 --- a/src/plugins/ci.jl +++ b/src/plugins/ci.jl @@ -41,8 +41,10 @@ Integrates your packages with [Travis CI](https://travis-ci.com). - `linux::Bool`: Whether or not to run builds on Linux. - `osx::Bool`: Whether or not to run builds on OSX (MacOS). - `windows::Bool`: Whether or not to run builds on Windows. -- `x86::Bool`: Whether or not to run builds on 32-bit systems, in addition to the default 64-bit builds. -- `coverage::Bool`: Whether or not to publish code coverage (another code coverage plugin such as [`Codecov`](@ref) must also be included). +- `x86::Bool`: Whether or not to run builds on 32-bit systems, + in addition to the default 64-bit builds. +- `coverage::Bool`: Whether or not to publish code coverage. + Another code coverage plugin such as [`Codecov`](@ref) must also be included. $EXTRA_VERSIONS_DOC """ @with_kw_noshow struct TravisCI <: BasicPlugin @@ -106,12 +108,15 @@ end extra_versions=$DEFAULT_CI_VERSIONS, ) -Integrates your packages with [AppVeyor](https://appveyor.com) via [AppVeyor.jl](https://github.com/JuliaCI/Appveyor.jl). +Integrates your packages with [AppVeyor](https://appveyor.com) +via [AppVeyor.jl](https://github.com/JuliaCI/Appveyor.jl). ## Keyword Arguments - `file::AbstractString`: Template file for `.appveyor.yml`. -- `x86::Bool`: Whether or not to run builds on 32-bit systems, in addition to the default 64-bit builds. -- `coverage::Bool`: Whether or not to publish code coverage ([`Codecov`](@ref) must also be included). +- `x86::Bool`: Whether or not to run builds on 32-bit systems, + in addition to the default 64-bit builds. +- `coverage::Bool`: Whether or not to publish code coverage. + [`Codecov`](@ref) must also be included. $EXTRA_VERSIONS_DOC """ @with_kw_noshow struct AppVeyor <: BasicPlugin @@ -156,16 +161,19 @@ end extra_versions=$DEFAULT_CI_VERSIONS, ) -Integrates your packages with [Cirrus CI](https://cirrus-ci.org) via [CirrusCI.jl](https://github.com/ararslan/CirrusCI.jl). +Integrates your packages with [Cirrus CI](https://cirrus-ci.org) +via [CirrusCI.jl](https://github.com/ararslan/CirrusCI.jl). ## Keyword Arguments - `file::AbstractString`: Template file for `.cirrus.yml`. - `image::AbstractString`: The FreeBSD image to be used. -- `coverage::Bool`: Whether or not to publish code coverage ([`Codecov`](@ref) must also be included). +- `coverage::Bool`: Whether or not to publish code coverage. + [`Codecov`](@ref) must also be included. $EXTRA_VERSIONS_DOC !!! note - Code coverage submission from Cirrus CI is not yet supported by [Coverage.jl](https://github.com/JuliaCI/Coverage.jl). + Code coverage submission from Cirrus CI is not yet supported by + [Coverage.jl](https://github.com/JuliaCI/Coverage.jl). """ @with_kw_noshow struct CirrusCI <: BasicPlugin file::String = default_file("cirrus.yml") @@ -202,7 +210,7 @@ end extra_versions=$DEFAULT_CI_VERSIONS_NO_NIGHTLY, ) -Integrates your packages with [GitLab CI](https://docs.gitlab.com/ce/ci/). +Integrates your packages with [GitLab CI](https://docs.gitlab.com/ce/ci). ## Keyword Arguments - `file::AbstractString`: Template file for `.gitlab-ci.yml`. @@ -270,7 +278,7 @@ Integrates your packages with [Drone CI](https://drone.io). For example, you might want to generate a `.drone.yml` instead of the default Starlark file. - `amd64::Bool`: Whether or not to run builds on AMD64. - `arm::Bool`: Whether or not to run builds on ARM (32-bit). -- `arm::Bool`: Whether or not to run builds on ARM64. +- `arm64::Bool`: Whether or not to run builds on ARM64. $EXTRA_VERSIONS_DOC !!! note diff --git a/src/plugins/coverage.jl b/src/plugins/coverage.jl index 448cc36..50674bb 100644 --- a/src/plugins/coverage.jl +++ b/src/plugins/coverage.jl @@ -6,7 +6,8 @@ const COVERAGE_GITIGNORE = ["*.jl.cov", "*.jl.*.cov", "*.jl.mem"] Sets up code coverage submission from CI to [Codecov](https://codecov.io). ## Keyword Arguments -- `file::Union{AbstractString, Nothing}`: Template file for `.codecov.yml`, or `nothing` to create no file. +- `file::Union{AbstractString, Nothing}`: Template file for `.codecov.yml`, + or `nothing` to create no file. """ @with_kw_noshow struct Codecov <: BasicPlugin file::Union{String, Nothing} = nothing @@ -27,7 +28,8 @@ badges(::Codecov) = Badge( Sets up code coverage submission from CI to [Coveralls](https://coveralls.io). ## Keyword Arguments -- `file::Union{AbstractString, Nothing}`: Template file for `.coveralls.yml`, or `nothing` to create no file. +- `file::Union{AbstractString, Nothing}`: Template file for `.coveralls.yml`, + or `nothing` to create no file. """ @with_kw_noshow struct Coveralls <: BasicPlugin file::Union{String, Nothing} = nothing diff --git a/src/plugins/develop.jl b/src/plugins/develop.jl index a06fef7..835f271 100644 --- a/src/plugins/develop.jl +++ b/src/plugins/develop.jl @@ -2,7 +2,9 @@ Develop() Adds generated packages to the current environment by `dev`ing them. -See the Pkg documentation [here](https://julialang.github.io/Pkg.jl/v1/managing-packages/#Developing-packages-1) for more details. +See the Pkg documentation +[here](https://julialang.github.io/Pkg.jl/v1/managing-packages/#Developing-packages-1) +for more details. """ struct Develop <: Plugin end diff --git a/src/plugins/documenter.jl b/src/plugins/documenter.jl index 291639f..87541b3 100644 --- a/src/plugins/documenter.jl +++ b/src/plugins/documenter.jl @@ -13,23 +13,29 @@ const DOCUMENTER_DEP = PackageSpec(; ) Sets up documentation generation via [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). -Documentation deployment depends on `T`, where `T` is some supported CI plugin, or `Nothing` to only support local documentation builds. +Documentation deployment depends on `T`, where `T` is some supported CI plugin, +or `Nothing` to only support local documentation builds. ## Supported Type Parameters -- `TravisCI`: Deploys documentation to [GitHub Pages](https://pages.github.com) with the help of [`TravisCI`](@ref). -- `GitLabCI`: Deploys documentation to [GitLab Pages](https://pages.gitlab.com) with the help of [`GitLabCI`](@ref). +- `TravisCI`: Deploys documentation to [GitHub Pages](https://pages.github.com) + with the help of [`TravisCI`](@ref). +- `GitLabCI`: Deploys documentation to [GitLab Pages](https://pages.gitlab.com) + with the help of [`GitLabCI`](@ref). - `Nothing` (default): Does not set up documentation deployment. ## Keyword Arguments - `make_jl::AbstractString`: Template file for `make.jl`. - `index_md::AbstractString`: Template file for `index.md`. - `assets::Vector{<:AbstractString}`: Extra assets for the generated site. -- `canonical_url::Union{Function, Nothing}`: A function to generate the documentation site's canonical URL. - The default value will compute GitHub Pages and GitLab Pages URLs for [`TravisCI`](@ref) and [`GitLabCI`](@ref), respectively. +- `canonical_url::Union{Function, Nothing}`: A function to generate the site's canonical URL. + The default value will compute GitHub Pages and GitLab Pages URLs + for [`TravisCI`](@ref) and [`GitLabCI`](@ref), respectively. + If set to `nothing`, no canonical URL is set. - `makedocs_kwargs::Dict{Symbol}`: Extra keyword arguments to be inserted into `makedocs`. !!! note - If deploying documentation with Travis CI, don't forget to complete [the required configuration](https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#SSH-Deploy-Keys-1). + If deploying documentation with Travis CI, don't forget to complete + [the required configuration](https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#SSH-Deploy-Keys-1). """ struct Documenter{T<:Union{TravisCI, GitLabCI, Nothing}} <: Plugin assets::Vector{String} diff --git a/src/plugins/git.jl b/src/plugins/git.jl index aaea917..d105f22 100644 --- a/src/plugins/git.jl +++ b/src/plugins/git.jl @@ -10,7 +10,8 @@ Creates a Git repository and a `.gitignore` file. If left unset, HTTPS is used. - `manifest::Bool`: Whether or not to commit `Manifest.toml`. - `gpgsign::Bool`: Whether or not to sign commits with your GPG key. - This option requires that the Git CLI is installed, and for you to have a GPG key associated with your committer identity. + This option requires that the Git CLI is installed, + and for you to have a GPG key associated with your committer identity. """ @with_kw_noshow struct Git <: Plugin ignore::Vector{String} = String[] diff --git a/src/plugins/license.jl b/src/plugins/license.jl index be8314a..e88bcbe 100644 --- a/src/plugins/license.jl +++ b/src/plugins/license.jl @@ -5,7 +5,8 @@ Creates a license file. ## Keyword Arguments - `name::AbstractString`: Name of a license supported by PkgTemplates. - Available licenses can be seen [here](https://github.com/invenia/PkgTemplates.jl/tree/master/templates/licenses). + Available licenses can be seen + [here](https://github.com/invenia/PkgTemplates.jl/tree/master/templates/licenses). - `path::Union{AbstractString, Nothing}`: Path to a custom license file. This keyword takes priority over `name`. - `destination::AbstractString`: File destination, relative to the repository root. diff --git a/src/plugins/tests.jl b/src/plugins/tests.jl index 8281be6..955c0f5 100644 --- a/src/plugins/tests.jl +++ b/src/plugins/tests.jl @@ -9,10 +9,12 @@ Sets up testing for packages. ## Keyword Arguments - `file::AbstractString`: Template file for `runtests.jl`. - `project::Bool`: Whether or not to create a new project for tests (`test/Project.toml`). - See [here](https://julialang.github.io/Pkg.jl/v1/creating-packages/#Test-specific-dependencies-in-Julia-1.2-and-above-1) for more details. + See [here](https://julialang.github.io/Pkg.jl/v1/creating-packages/#Test-specific-dependencies-in-Julia-1.2-and-above-1) + for more details. !!! note - Managing test dependencies with `test/Project.toml` is only supported in Julia 1.2 and later. + Managing test dependencies with `test/Project.toml` is only supported + in Julia 1.2 and later. """ @with_kw_noshow struct Tests <: BasicPlugin file::String = default_file("test", "runtests.jl") diff --git a/src/template.jl b/src/template.jl index af768cf..c079f75 100644 --- a/src/template.jl +++ b/src/template.jl @@ -21,7 +21,8 @@ A configuration used to generate packages. The default value comes from the global Git config (`github.user`). If no value is obtained, many plugins that use this value will not work. - `authors::Union{AbstractString, Vector{<:AbstractString}}="$(default_authors())"`: Package authors. - Like `user`, it takes its default value from the global Git config (`user.name` and `user.email`). + Like `user`, it takes its default value from the global Git config + (`user.name` and `user.email`). ### Package Options - `dir::AbstractString="$(contractuser(Pkg.devdir()))"`: Directory to place packages in. @@ -31,7 +32,8 @@ A configuration used to generate packages. ### Template Plugins - `plugins::Vector{<:Plugin}=Plugin[]`: A list of [`Plugin`](@ref)s used by the template. - `disable_defaults::Vector{DataType}=DataType[]`: Default plugins to disable. - The default plugins are [`ProjectFile`](@ref), [`SrcDir`](@ref), [`Tests`](@ref), [`Readme`](@ref), [`License`](@ref), and [`Git`](@ref). + The default plugins are [`ProjectFile`](@ref), [`SrcDir`](@ref), [`Tests`](@ref), + [`Readme`](@ref), [`License`](@ref), and [`Git`](@ref). To override a default plugin instead of disabling it altogether, supply it via `plugins`. ---