2017-08-11 22:18:09 +00:00
|
|
|
"""
|
2017-08-17 22:06:05 +00:00
|
|
|
Add a `Documenter` subtype to a template's plugins to add support for documentation
|
|
|
|
generation via [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl).
|
|
|
|
"""
|
2017-08-17 06:57:58 +00:00
|
|
|
abstract type Documenter <: CustomPlugin end
|
2017-08-11 22:18:09 +00:00
|
|
|
|
2018-09-28 20:30:10 +00:00
|
|
|
function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString)
|
|
|
|
path = joinpath(t.dir, pkg_name)
|
2017-08-11 22:18:09 +00:00
|
|
|
docs_dir = joinpath(path, "docs", "src")
|
|
|
|
mkpath(docs_dir)
|
2018-09-28 20:30:10 +00:00
|
|
|
|
2018-11-02 21:38:17 +00:00
|
|
|
tab = repeat(" ", 4)
|
2018-09-28 20:30:10 +00:00
|
|
|
assets_string = if !isempty(p.assets)
|
2017-08-11 22:18:09 +00:00
|
|
|
mkpath(joinpath(docs_dir, "assets"))
|
2018-09-28 20:30:10 +00:00
|
|
|
for file in p.assets
|
2017-08-11 22:18:09 +00:00
|
|
|
cp(file, joinpath(docs_dir, "assets", basename(file)))
|
|
|
|
end
|
2018-09-28 20:30:10 +00:00
|
|
|
|
2017-08-11 22:18:09 +00:00
|
|
|
# We want something that looks like the following:
|
|
|
|
# [
|
|
|
|
# assets/file1,
|
|
|
|
# assets/file2,
|
|
|
|
# ]
|
2018-09-28 20:30:10 +00:00
|
|
|
s = "[\n"
|
|
|
|
for asset in p.assets
|
|
|
|
s *= """$(tab^2)"assets/$(basename(asset))",\n"""
|
2017-08-11 22:18:09 +00:00
|
|
|
end
|
2018-09-28 20:30:10 +00:00
|
|
|
s *= "$tab]"
|
|
|
|
|
|
|
|
s
|
2017-08-14 22:49:44 +00:00
|
|
|
else
|
2018-09-28 20:30:10 +00:00
|
|
|
"[]"
|
2017-08-11 22:18:09 +00:00
|
|
|
end
|
2018-09-28 20:30:10 +00:00
|
|
|
|
2018-11-02 22:23:40 +00:00
|
|
|
kwargs_string = if :additional_kwargs in fieldnames(typeof(p))
|
2018-11-05 16:49:57 +00:00
|
|
|
standard_kwargs = ["modules", "format", "pages", "repo", "sitename", "authors", "assets"]
|
2018-11-02 21:38:17 +00:00
|
|
|
|
|
|
|
# We want something that looks like the following:
|
|
|
|
# key1="val1",
|
|
|
|
# key2="val2",
|
|
|
|
#
|
2018-11-05 16:49:57 +00:00
|
|
|
valid_keys = [k for k in keys(p.additional_kwargs) if k ∉ standard_kwargs]
|
|
|
|
if length(p.additional_kwargs) > length(valid_keys)
|
|
|
|
invalid_keys = (repr(k) for k in keys(p.additional_kwargs) if k in standard_kwargs)
|
|
|
|
@warn string(
|
|
|
|
"Ignoring predefined Documenter kwargs ",
|
|
|
|
join(invalid_keys, ", "),
|
|
|
|
" from additional kwargs."
|
|
|
|
)
|
|
|
|
end
|
|
|
|
join(string(tab, k, "=", repr(p.additional_kwargs[k]), ",\n") for k in valid_keys)
|
2018-11-02 21:38:17 +00:00
|
|
|
else
|
|
|
|
""
|
|
|
|
end
|
|
|
|
|
2018-09-28 21:38:48 +00:00
|
|
|
make = """
|
2017-08-11 22:18:09 +00:00
|
|
|
using Documenter, $pkg_name
|
|
|
|
|
2017-08-18 21:08:48 +00:00
|
|
|
makedocs(;
|
2017-08-11 22:18:09 +00:00
|
|
|
modules=[$pkg_name],
|
|
|
|
format=:html,
|
|
|
|
pages=[
|
|
|
|
"Home" => "index.md",
|
|
|
|
],
|
2018-09-28 20:30:10 +00:00
|
|
|
repo="https://$(t.host)/$(t.user)/$pkg_name.jl/blob/{commit}{path}#L{line}",
|
2017-08-11 22:18:09 +00:00
|
|
|
sitename="$pkg_name.jl",
|
2018-09-28 20:30:10 +00:00
|
|
|
authors="$(t.authors)",
|
2017-08-15 14:19:37 +00:00
|
|
|
assets=$assets_string,
|
2018-11-02 21:38:17 +00:00
|
|
|
$kwargs_string)
|
2017-08-11 22:18:09 +00:00
|
|
|
"""
|
2018-09-28 21:38:48 +00:00
|
|
|
docs = """
|
|
|
|
# $pkg_name.jl
|
2017-08-11 22:18:09 +00:00
|
|
|
|
2018-09-28 21:38:48 +00:00
|
|
|
```@index
|
|
|
|
```
|
2018-09-28 20:30:10 +00:00
|
|
|
|
2018-09-28 21:38:48 +00:00
|
|
|
```@autodocs
|
|
|
|
Modules = [$pkg_name]
|
|
|
|
```
|
|
|
|
"""
|
|
|
|
|
|
|
|
gen_file(joinpath(dirname(docs_dir), "make.jl"), make)
|
|
|
|
gen_file(joinpath(docs_dir, "index.md"), docs)
|
2017-08-11 22:18:09 +00:00
|
|
|
end
|
2017-08-28 21:34:34 +00:00
|
|
|
|
2018-09-19 21:23:11 +00:00
|
|
|
function Base.show(io::IO, p::Documenter)
|
2017-12-12 15:15:55 +00:00
|
|
|
spc = " "
|
2018-09-17 20:26:37 +00:00
|
|
|
println(io, "$(nameof(typeof(p))):")
|
2017-12-01 17:33:57 +00:00
|
|
|
|
|
|
|
n = length(p.assets)
|
|
|
|
s = n == 1 ? "" : "s"
|
2017-12-12 15:15:55 +00:00
|
|
|
print(io, "$spc→ $n asset file$s")
|
2017-12-01 17:33:57 +00:00
|
|
|
if n == 0
|
|
|
|
println(io)
|
|
|
|
else
|
2018-09-19 19:57:21 +00:00
|
|
|
println(io, ": $(join(map(a -> replace(a, homedir() => "~"), p.assets), ", "))")
|
2017-12-01 17:33:57 +00:00
|
|
|
end
|
|
|
|
|
|
|
|
n = length(p.gitignore)
|
|
|
|
s = n == 1 ? "" : "s"
|
2017-12-12 15:15:55 +00:00
|
|
|
print(io, "$spc→ $n gitignore entrie$s")
|
2017-12-01 17:33:57 +00:00
|
|
|
n > 0 && print(io, ": $(join(map(g -> "\"$g\"", p.gitignore), ", "))")
|
|
|
|
end
|
|
|
|
|
2018-09-28 20:30:10 +00:00
|
|
|
function interactive(t::Type{<:Documenter})
|
|
|
|
name = string(nameof(t))
|
|
|
|
print("$name: Enter any Documenter asset files (separated by spaces) []: ")
|
|
|
|
return t(; assets=string.(split(readline())))
|
2017-08-28 21:34:34 +00:00
|
|
|
end
|