Merge pull request #31 from invenia/sm/update-docs

Adds additional kwargs to Documenter plugin

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

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"))

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)