From d209823a57da6ba79defac5604d8ff6e377e3f77 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Fri, 25 Jan 2019 23:33:17 -0800 Subject: [PATCH 1/6] Add GitLabPages plugin --- defaults/gitlab-ci.yml | 18 ++++++++++++++ src/PkgTemplates.jl | 4 ++- src/plugins/gitlabpages.jl | 51 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 src/plugins/gitlabpages.jl diff --git a/defaults/gitlab-ci.yml b/defaults/gitlab-ci.yml index 35f9ffe..1304a94 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}} +Documentation: + 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/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..70e96c7 --- /dev/null +++ b/src/plugins/gitlabpages.jl @@ -0,0 +1,51 @@ +""" + 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) + return [ + #= + format(Badge( + "Stable", + "https://img.shields.io/badge/docs-stable-blue.svg", + "https://$user.gitlab.io/$pkg_name.jl/stable" + )), + =# + 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 From 591e687705c82a3f811a6ace33b8790af7c2138e Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Tue, 29 Jan 2019 19:11:20 -0800 Subject: [PATCH 2/6] GitLab Pages require the job name to be "pages" See: https://docs.gitlab.com/ee/ci/yaml/README.html#pages https://docs.gitlab.com/ee/user/project/pages/introduction.html#gitlab-pages-requirements --- defaults/gitlab-ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/defaults/gitlab-ci.yml b/defaults/gitlab-ci.yml index 1304a94..ffbb420 100644 --- a/defaults/gitlab-ci.yml +++ b/defaults/gitlab-ci.yml @@ -7,7 +7,7 @@ Julia {{VERSION}}: - 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}} -Documentation: +pages: image: julia:{{VERSION}} stage: deploy script: From b30871fa7fcbf5b1822e13e7cee3a7f2fb962f10 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Thu, 31 Jan 2019 19:31:30 -0800 Subject: [PATCH 3/6] Test GitLabPages --- test/plugins/gitlabpages.jl | 60 +++++++++++++++++++++++++++++++++++++ test/tests.jl | 1 + 2 files changed, 61 insertions(+) create mode 100644 test/plugins/gitlabpages.jl 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 From af79ad45db6513379886f195f782161cbc66eed7 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Thu, 31 Jan 2019 19:45:51 -0800 Subject: [PATCH 4/6] Comment why only dev badge is included --- src/plugins/gitlabpages.jl | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/src/plugins/gitlabpages.jl b/src/plugins/gitlabpages.jl index 70e96c7..3f2c032 100644 --- a/src/plugins/gitlabpages.jl +++ b/src/plugins/gitlabpages.jl @@ -24,14 +24,10 @@ struct GitLabPages <: Documenter 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( - "Stable", - "https://img.shields.io/badge/docs-stable-blue.svg", - "https://$user.gitlab.io/$pkg_name.jl/stable" - )), - =# format(Badge( "Dev", "https://img.shields.io/badge/docs-dev-blue.svg", From 9c1f16fb0c1f525665555f6e285cf7bb305f34b9 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Thu, 31 Jan 2019 19:46:57 -0800 Subject: [PATCH 5/6] Include GitLabPages in documentation --- docs/src/pages/plugins.md | 1 + 1 file changed, 1 insertion(+) 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 ``` From a338ecbc6bbe77a556b50551d650f21f077e852b Mon Sep 17 00:00:00 2001 From: Chris de Graaf Date: Tue, 5 Feb 2019 09:01:09 -0600 Subject: [PATCH 6/6] Indent a list --- defaults/gitlab-ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/defaults/gitlab-ci.yml b/defaults/gitlab-ci.yml index ffbb420..ab0908b 100644 --- a/defaults/gitlab-ci.yml +++ b/defaults/gitlab-ci.yml @@ -22,5 +22,5 @@ pages: paths: - public only: - - master + - master {{/DOCUMENTER}}