diff --git a/src/plugins/documenter.jl b/src/plugins/documenter.jl index a7eb250..1e2119f 100644 --- a/src/plugins/documenter.jl +++ b/src/plugins/documenter.jl @@ -1,7 +1,21 @@ +const STANDARD_KWS = [:modules, :format, :pages, :repo, :sitename, :authors, :assets] + """ Add a `Documenter` subtype to a template's plugins to add support for documentation generation via [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). - """ + +By default, the plugin generates a minimal index.md and a make.jl file. The make.jl +file contains the Documenter.makedocs command with predefined values for `modules`, +`format`, `pages`, `repo`, `sitename`, and `authors`. + +The subtype is expected to include the following fields: +* `assets::Vector{AbstractString}`, a list of filenames to be included as the `assets` +kwarg to `makedocs` +* `gitignore::Vector{AbstractString}`, a list of files to be added to the `.gitignore` + +It may optionally include the field `additional_kwargs::Union{AbstractDict, NamedTuple}` +to allow additional kwargs to be added to `makedocs`. +""" abstract type Documenter <: CustomPlugin end function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString) @@ -9,6 +23,7 @@ function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString) docs_dir = joinpath(path, "docs", "src") mkpath(docs_dir) + tab = repeat(" ", 4) assets_string = if !isempty(p.assets) mkpath(joinpath(docs_dir, "assets")) for file in p.assets @@ -20,7 +35,6 @@ function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString) # assets/file1, # assets/file2, # ] - tab = repeat(" ", 4) s = "[\n" for asset in p.assets s *= """$(tab^2)"assets/$(basename(asset))",\n""" @@ -32,6 +46,27 @@ function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString) "[]" end + kwargs_string = if :additional_kwargs in fieldnames(typeof(p)) && + fieldtype(typeof(p), :additional_kwargs) <: Union{AbstractDict, NamedTuple} + # We want something that looks like the following: + # key1="val1", + # key2="val2", + # + kws = [keys(p.additional_kwargs)...] + valid_keys = filter(k -> !in(Symbol(k), STANDARD_KWS), kws) + if length(p.additional_kwargs) > length(valid_keys) + invalid_keys = filter(k -> in(Symbol(k), STANDARD_KWS), kws) + @warn string( + "Ignoring predefined Documenter kwargs ", + join(map(repr, invalid_keys), ", "), + " from additional kwargs" + ) + end + join(map(k -> string(tab, k, "=", repr(p.additional_kwargs[k]), ",\n"), valid_keys)) + else + "" + end + make = """ using Documenter, $pkg_name @@ -45,7 +80,7 @@ function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString) sitename="$pkg_name.jl", authors="$(t.authors)", assets=$assets_string, - ) + $kwargs_string) """ docs = """ # $pkg_name.jl diff --git a/test/runtests.jl b/test/runtests.jl index 8bcd9a8..13fa915 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -7,7 +7,7 @@ using Pkg import PkgTemplates: badges, version_floor, substitute, read_license, gen_file, gen_readme, gen_tests, gen_license, gen_require, gen_gitignore, gen_plugin, show_license, LICENSES, LICENSE_DIR, Plugin, GenericPlugin, CustomPlugin, Badge, format, interactive, - DEFAULTS_DIR + DEFAULTS_DIR, Documenter mktempdir() do temp_dir mkdir(joinpath(temp_dir, "dev")) diff --git a/test/tests.jl b/test/tests.jl index be1a9ae..f702fea 100644 --- a/test/tests.jl +++ b/test/tests.jl @@ -397,4 +397,49 @@ end include(joinpath("plugins", "githubpages.jl")) end +# A Documenter with extra kwargs +struct Qux <: Documenter + assets::Vector{AbstractString} + additional_kwargs::Union{AbstractDict, NamedTuple} +end + +@testset "Documenter add kwargs" begin + t = Template(; user=me) + pkg_dir = joinpath(t.dir, test_pkg) + + function check_kwargs(kwargs, warn_str) + p = Qux([], kwargs) + @test_logs (:warn, warn_str) gen_plugin(p, t, test_pkg) + + make = readchomp(joinpath(pkg_dir, "docs", "make.jl")) + @test occursin("\n stringarg=\"string\",\n", make) + @test occursin("\n strict=true,\n", make) + @test occursin("\n checkdocs=:none,\n", make) + + @test !occursin("format=:markdown", make) + @test occursin("format=:html", make) + rm(pkg_dir; recursive=true) + end + # Test with string kwargs + kwargs = Dict("checkdocs" => :none, + "strict" => true, + "format" => :markdown, + "stringarg" => "string", + ) + warn_str = "Ignoring predefined Documenter kwargs \"format\" from additional kwargs" + check_kwargs(kwargs, warn_str) + + kwargs = Dict(:checkdocs => :none, + :strict => true, + :format => :markdown, + :stringarg => "string", + ) + warn_str = "Ignoring predefined Documenter kwargs :format from additional kwargs" + check_kwargs(kwargs, warn_str) + + kwargs = (checkdocs = :none, strict = true, format = :markdown, stringarg = "string") + warn_str = "Ignoring predefined Documenter kwargs :format from additional kwargs" + check_kwargs(kwargs, warn_str) +end + rm(test_file)