Minor bug/doc fixes

docs/src/developer.md

@@ -22,7 +22,7 @@ BasicPlugin
 The package generation process looks basically like this:
 
 ```
-- create directory for the package
+- create empty directory for the package
 - for each plugin, ordered by priority:
   - run plugin prehook
 - for each plugin, ordered by priority:
@@ -43,7 +43,7 @@ For example, the [`Git`](@ref) plugin uses [`posthook`](@ref) to commit all gene
 
 But what about dependencies within the same stage?
 In this case, we have [`priority`](@ref) to define which plugins go when.
-The [`Git`](@ref) plugin also uses this function to lower its priority, so that even if other plugins generate files in their posthooks, they still get committed.
+The [`Git`](@ref) plugin also uses this function to lower its posthook's priority, so that even if other plugins generate files in their posthooks, they still get committed (provided that those plugins didn't set an even lower priority).
 
 ```@docs
 prehook
@@ -146,7 +146,7 @@ For more information on text templating, see the [`BasicPlugin` Walkthrough](@re
 
 ### Example: `Git`
 
-```
+```julia
 struct Git <: Plugin end
 
 priority(::Git, ::typeof(posthook)) = 5
@@ -174,15 +174,15 @@ function posthook(::Git, ::Template, pkg_dir::AbstractString)
 end
 ```
 
-As previously mentioned, we use [`priority`](@ref) to make sure that we commit all generated files.
+All three hooks are implemented:
 
-Then, all three hooks are implemented:
+- [`prehook`](@ref) creates the Git repository for the package.
+- [`hook`](@ref) generates the `.gitignore` file, using the special [`gitignore`](@ref) function.
+- [`posthook`](@ref) adds and commits all the generated files.
 
-- [`prehook`](@ref) creates the Git repository for the package
+As previously mentioned, we use [`priority`](@ref) to make sure that we wait until all other plugins are finished their work before committing files.
-- [`hook`](@ref) generates the `.gitignore` file, using the special [`gitignore`](@ref) function
-- [`posthook`](@ref) adds and commits all generated files
 
-Hopefully, this demonstrates the level of control you have over the package generation process when developing plugins.
+Hopefully, this demonstrates the level of control you have over the package generation process when developing plugins, and when it makes sense to exercise that power!
 
 ## `BasicPlugin` Walkthrough
 

src/plugin.jl

@@ -137,8 +137,8 @@ end
 """
     prehook(::Plugin, ::Template, pkg_dir::AbstractString)
 
-Do some work associated with a plugin **before** any files are generated.
+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.
+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.
@@ -146,36 +146,34 @@ At this point, `pkg_dir` is an empty directory that will eventually contain the
 """
 prehook(::Plugin, ::Template, ::AbstractString) = nothing
 
+"""
+    hook(::Plugin, ::Template, pkg_dir::AbstractString)
+
+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).
+
+!!! 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`).
+"""
+hook(::Plugin, ::Template, ::AbstractString) = nothing
+
+"""
+    posthook(::Plugin, ::Template, pkg_dir::AbstractString)
+
+Stage 3 of the package generation pipeline (the "after" stage, in general).
+At this point, both the [`prehook`](@ref)s and [`hook`](@ref)s have run.
+"""
+posthook(::Plugin, ::Template, ::AbstractString) = nothing
+
 function prehook(p::T, ::Template, ::AbstractString) where T <: BasicPlugin
     src = source(p)
     src === nothing && return
     isfile(src) || throw(ArgumentError("$(nameof(T)): The file $src does not exist"))
 end
 
-"""
-    posthook(::Plugin, ::Template, pkg_dir::AbstractString)
-
-Do some work associated with a plugin **after** files have been generated.
-"""
-posthook(::Plugin, ::Template, ::AbstractString) = nothing
-
-"""
-    hook(::Plugin, ::Template, pkg_dir::AbstractString)
-
-Perform any work associated with a plugin.
-`pkg_dir` is the directory in which the package is being generated (so `basename(pkg_dir)` is the package name).
-
-For [`Plugin`](@ref)s that are not [`BasicPlugin`](@ref)s, this is the only function that really needs to be implemented.
-If you want your plugin to do something during the main phase of package generation, you should implement it here.
-
-See also: [`prehook`](@ref) and [`posthook`](@ref).
-
-!!! 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 no reason to subtype `BasicPlugin`).
-"""
-hook(::Plugin, ::Template, ::AbstractString) = nothing
-
 function hook(p::BasicPlugin, t::Template, pkg_dir::AbstractString)
     source(p) === nothing && return
     pkg = basename(pkg_dir)

src/plugins/ci.jl

@@ -198,7 +198,7 @@ end
     GitLabCI(;
         file="$(contractuser(default_file("gitlab-ci.yml")))",
         coverage=true,
-        extra_versions=$DEFAULT_CI_VERSIONS,
+        extra_versions=$(map(format_version, [default_version(), VERSION])),
     )
 
 Integrates your packages with [GitLab CI](https://docs.gitlab.com/ce/ci/).

src/plugins/citation.jl

@@ -1,8 +1,5 @@
 """
-    Citation(;
+    Citation(; file="$(contractuser(default_file("CITATION.bib")))", readme=false)
-        file="$(contractuser(default_file("CITATION.bib")))",
-        readme=false,
-    )
 
 Creates a `CITATION.bib` file for citing package repositories.
 

src/template.jl

@@ -21,7 +21,6 @@ A configuration used to generate packages.
   The default value comes from the global Git config (`github.user`).
   If no value is obtained, an `ArgumentError` is thrown.
 - `authors::Union{AbstractString, Vector{<:AbstractString}}="$(default_authors())"`: Package authors.
-  Supply a string for one author or an array for multiple.
   Like `user`, it takes its default value from the global Git config (`user.name` and `user.email`).
 
 ### Package Options

test/fixtures/AllPlugins/docs/src/index.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = AllPlugins
+```
+
 # AllPlugins
 
 ```@index

test/git.jl

@@ -38,7 +38,7 @@
     @testset "Adds version to commit message" begin
         # We're careful to avoid a Pkg.update as it triggers Cassette#130.
         t = tpl(; disable_defaults=[Tests], plugins=[Git()])
-        mock(CTX, Pkg.installed => () -> Dict("PkgTemplates" => v"1.2.3")) do _pi
+        mock(Pkg.installed => () -> Dict("PkgTemplates" => v"1.2.3")) do _pi
             with_pkg(t) do pkg
                 pkg_dir = joinpath(t.dir, pkg)
                 LibGit2.with(GitRepo(pkg_dir)) do repo

test/runtests.jl

@@ -20,7 +20,6 @@ Random.seed!(1)
 tpl(; kwargs...) = Template(; user=USER, kwargs...)
 
 const PKG = Ref("A")
-const CTX = gensym()
 
 # Generate an unused package name.
 pkgname() = PKG[] *= "a"

test/show.jl

@@ -35,7 +35,6 @@ const LICENSES_DIR = joinpath(TEMPLATES_DIR, "licenses")
                   ssh: false
                   manifest: false
                   gpgsign: false
-                  ignore_manifest: true
                 License:
                   path: "$(joinpath(LICENSES_DIR, "MIT"))"
                   destination: "LICENSE"

test/template.jl

@@ -67,7 +67,7 @@ end
 
     t = tpl()
     pkg = pkgname()
-    mock(CTX, LibGit2.init => dir -> (@test isdir(dir); error())) do _init
+    mock(LibGit2.init => dir -> (@test isdir(dir); error())) do _init
         @test_throws ErrorException @suppress t(pkg)
     end
     @test !isdir(joinpath(t.dir, pkg))