Merge pull request #54 from tkf/gitlabpages

Add GitLabPages plugin

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}}

docs/src/pages/plugins.md

@@ -28,4 +28,5 @@ Coveralls
 ```@docs
 Documenter
 GitHubPages
+GitLabPages
 ```

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

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

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)

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