diff --git a/defaults/gitlab-ci.yml b/defaults/gitlab-ci.yml index 35f9ffe..ab0908b 100644 --- a/defaults/gitlab-ci.yml +++ b/defaults/gitlab-ci.yml @@ -6,3 +6,21 @@ Julia {{VERSION}}: after_script: - julia -e 'using Printf; using Pkg; Pkg.add("Coverage"); using Coverage; c, t = get_summary(process_folder()); @printf "Test Coverage %.2f%%\n" 100c/t' {{/GITLABCOVERAGE}} +{{#DOCUMENTER}} +pages: + image: julia:{{VERSION}} + stage: deploy + script: + - julia --project=docs -e ' + using Pkg; + Pkg.develop(PackageSpec(path=pwd())); + Pkg.instantiate(); + include("docs/make.jl");' + - mkdir -p public + - mv docs/build public/dev + artifacts: + paths: + - public + only: + - master +{{/DOCUMENTER}} diff --git a/docs/src/pages/plugins.md b/docs/src/pages/plugins.md index 725ff87..6b643e7 100644 --- a/docs/src/pages/plugins.md +++ b/docs/src/pages/plugins.md @@ -28,4 +28,5 @@ Coveralls ```@docs Documenter GitHubPages +GitLabPages ``` diff --git a/src/PkgTemplates.jl b/src/PkgTemplates.jl index d49547e..eda0742 100644 --- a/src/PkgTemplates.jl +++ b/src/PkgTemplates.jl @@ -19,6 +19,7 @@ export available_licenses, # Plugins. GitHubPages, + GitLabPages, AppVeyor, TravisCI, GitLabCI, @@ -42,8 +43,9 @@ include(joinpath("plugins", "codecov.jl")) include(joinpath("plugins", "travisci.jl")) include(joinpath("plugins", "gitlabci.jl")) include(joinpath("plugins", "githubpages.jl")) +include(joinpath("plugins", "gitlabpages.jl")) const DEFAULTS_DIR = normpath(joinpath(@__DIR__, "..", "defaults")) -const BADGE_ORDER = [GitHubPages, TravisCI, AppVeyor, GitLabCI, Codecov, Coveralls] +const BADGE_ORDER = [GitHubPages, GitLabPages, TravisCI, AppVeyor, GitLabCI, Codecov, Coveralls] end diff --git a/src/plugins/gitlabpages.jl b/src/plugins/gitlabpages.jl new file mode 100644 index 0000000..3f2c032 --- /dev/null +++ b/src/plugins/gitlabpages.jl @@ -0,0 +1,47 @@ +""" + GitLabPages(; assets::Vector{<:AbstractString}=String[]) -> GitLabPages + +Add `GitLabPages` to a template's plugins to add [`Documenter`](@ref) support via GitLab +Pages, including automatic uploading of documentation from [`GitLabCI`](@ref). Also +adds appropriate badges to the README, and updates the `.gitignore` accordingly. + +# Keyword Arguments +* `assets::Vector{<:AbstractString}=String[]`: Array of paths to Documenter asset files. +""" +struct GitLabPages <: Documenter + gitignore::Vector{String} + assets::Vector{String} + + function GitLabPages(; assets::Vector{<:AbstractString}=String[]) + for file in assets + if !isfile(file) + throw(ArgumentError("Asset file $(abspath(file)) does not exist")) + end + end + # Windows Git recognizes these paths as well. + new(["/docs/build/", "/docs/site/"], abspath.(assets)) + end +end + +function badges(::GitLabPages, user::AbstractString, pkg_name::AbstractString) + # We are only including a badge for `dev` documentation since versioned documentation + # is not supported in GitLab pages yet. See: + # https://github.com/invenia/PkgTemplates.jl/pull/54 + return [ + format(Badge( + "Dev", + "https://img.shields.io/badge/docs-dev-blue.svg", + "https://$user.gitlab.io/$pkg_name.jl/dev" + )), + ] +end + +function gen_plugin(p::GitLabPages, t::Template, pkg_name::AbstractString) + invoke(gen_plugin, Tuple{Documenter, Template, AbstractString}, p, t, pkg_name) + return ["docs/"] +end + +function interactive(::Type{GitLabPages}) + print("GitLabPages: Enter any Documenter asset files (separated by spaces) []: ") + return GitLabPages(; assets=string.(split(readline()))) +end diff --git a/test/plugins/gitlabpages.jl b/test/plugins/gitlabpages.jl new file mode 100644 index 0000000..36283ec --- /dev/null +++ b/test/plugins/gitlabpages.jl @@ -0,0 +1,60 @@ +t = Template(; user=me) +pkg_dir = joinpath(t.dir, test_pkg) + +@testset "GitLabPages" begin + @testset "Plugin creation" begin + p = GitLabPages() + @test p.gitignore == ["/docs/build/", "/docs/site/"] + @test isempty(p.assets) + p = GitLabPages(; assets=[test_file]) + @test p.assets == [test_file] + @test_throws ArgumentError GitLabPages(; assets=[fake_path]) + end + + @testset "Badge generation" begin + p = GitLabPages() + @test badges(p, me, test_pkg) == [ + "[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://$me.gitlab.io/$test_pkg.jl/dev)" + ] + end + + @testset "File generation" begin + p = GitLabPages() + @test gen_plugin(p, t, test_pkg) == ["docs/"] + @test isdir(joinpath(pkg_dir, "docs")) + @test isfile(joinpath(pkg_dir, "docs", "make.jl")) + make = readchomp(joinpath(pkg_dir, "docs", "make.jl")) + @test occursin("assets=[]", make) + @test !occursin("deploydocs", make) + @test isdir(joinpath(pkg_dir, "docs", "src")) + @test isfile(joinpath(pkg_dir, "docs", "src", "index.md")) + index = readchomp(joinpath(pkg_dir, "docs", "src", "index.md")) + @test occursin("autodocs", index) + rm(joinpath(pkg_dir, "docs"); recursive=true) + p = GitLabPages(; assets=[test_file]) + @test gen_plugin(p, t, test_pkg) == ["docs/"] + make = readchomp(joinpath(pkg_dir, "docs", "make.jl")) + # Check the formatting of the assets list. + @test occursin( + strip(""" + assets=[ + "assets/$(basename(test_file))", + ] + """), + make, + ) + @test isfile(joinpath(pkg_dir, "docs", "src", "assets", basename(test_file))) + rm(joinpath(pkg_dir, "docs"); recursive=true) + end + + @testset "Package generation with GitLabPages plugin" begin + temp_dir = mktempdir() + t = Template(; user=me, dir=temp_dir, plugins=[GitLabCI(), GitLabPages()]) + generate(test_pkg, t; gitconfig=gitconfig) + + gitlab = read(joinpath(t.dir, test_pkg, ".gitlab-ci.yml"), String) + @test occursin("pages:", gitlab) + end +end + +rm(pkg_dir; recursive=true) diff --git a/test/tests.jl b/test/tests.jl index fa66648..142cba5 100644 --- a/test/tests.jl +++ b/test/tests.jl @@ -444,6 +444,7 @@ end include(joinpath("plugins", "codecov.jl")) include(joinpath("plugins", "coveralls.jl")) include(joinpath("plugins", "githubpages.jl")) + include(joinpath("plugins", "gitlabpages.jl")) end @testset "Documenter add kwargs" begin