Allow specifying devbranch for Documenter (#242)

src/plugins/documenter.jl

@@ -55,6 +55,7 @@ or `Nothing` to only support local documentation builds.
   for [`TravisCI`](@ref) and [`GitLabCI`](@ref), respectively.
   If set to `nothing`, no canonical URL is set.
 - `makedocs_kwargs::Dict{Symbol}`: Extra keyword arguments to be inserted into `makedocs`.
+- `devbranch::Union{AbstractString, Nothing}`: Branch that will trigger docs deployment.
 
 !!! note
     If deploying documentation with Travis CI, don't forget to complete
@@ -67,6 +68,7 @@ struct Documenter{T<:DeployStyle} <: Plugin
     canonical_url::Union{Function, Nothing}
     make_jl::String
     index_md::String
+    devbranch::Union{String, Nothing}
 end
 
 # Can't use @plugin because we're implementing our own no-arguments constructor.
@@ -77,8 +79,17 @@ function Documenter{T}(;
     canonical_url::Union{Function, Nothing}=make_canonical(T),
     make_jl::AbstractString=default_file("docs", "make.jl"),
     index_md::AbstractString=default_file("docs", "src", "index.md"),
+    devbranch::Union{String, Nothing}=nothing,
 ) where T <: DeployStyle
-    return Documenter{T}(assets, logo, makedocs_kwargs, canonical_url, make_jl, index_md)
+    return Documenter{T}(
+        assets,
+        logo,
+        makedocs_kwargs,
+        canonical_url,
+        make_jl,
+        index_md,
+        devbranch,
+    )
 end
 
 Documenter(; kwargs...) = Documenter{NoDeploy}(; kwargs...)
@@ -88,6 +99,7 @@ defaultkw(::Type{<:Documenter}, ::Val{:assets}) = String[]
 defaultkw(::Type{<:Documenter}, ::Val{:logo}) = Logo()
 defaultkw(::Type{<:Documenter}, ::Val{:make_jl}) = default_file("docs", "make.jl")
 defaultkw(::Type{<:Documenter}, ::Val{:index_md}) = default_file("docs", "src", "index.md")
+defaultkw(::Type{<:Documenter}, ::Val{:devbranch}) = nothing
 
 gitignore(::Documenter) = ["/docs/build/"]
 priority(::Documenter, ::Function) = DEFAULT_PRIORITY - 1  # We need SrcDir to go first.
@@ -121,6 +133,7 @@ view(p::Documenter, t::Template, pkg::AbstractString) = Dict(
     "PKG" => pkg,
     "REPO" => "$(t.host)/$(t.user)/$pkg.jl",
     "USER" => t.user,
+    "BRANCH" => p.devbranch === nothing ? default_branch(t) : p.devbranch,
 )
 
 function view(p::Documenter{<:GitHubPagesStyle}, t::Template, pkg::AbstractString)

src/template.jl

@@ -272,3 +272,8 @@ end
 
 # Call the default prompt method even if a specialized one exists.
 fallback_prompt(T::Type, name::Symbol) = prompt(Template, T, Val(name), nothing)
+
+function default_branch(t::Template)
+    git = getplugin(t, Git)
+    return git === nothing ? nothing : git.branch
+end

templates/docs/make.jl

@@ -32,5 +32,8 @@ makedocs(;
 
 deploydocs(;
     repo="{{{REPO}}}",
+{{#BRANCH}}
+    devbranch="{{{BRANCH}}}",
+{{/BRANCH}}
 )
 {{/HAS_DEPLOY}}

test/fixtures/WackyOptions/.github/workflows/ci.yml

@@ -40,3 +40,26 @@ jobs:
             ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()'
+      - run: |
+          julia --project=docs -e '
+            using Documenter: DocMeta, doctest
+            using WackyOptions
+            DocMeta.setdocmeta!(WackyOptions, :DocTestSetup, :(using WackyOptions); recursive=true)
+            doctest(WackyOptions)'
+      - run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

test/fixtures/WackyOptions/.gitlab-ci.yml

@@ -9,23 +9,3 @@ Julia 1.2:
   image: julia:1.2
   extends:
     - .script
-pages:
-  image: julia:1.2
-  stage: deploy
-  script:
-    - |
-      julia --project=docs -e '
-        using Pkg
-        Pkg.develop(PackageSpec(path=pwd()))
-        Pkg.instantiate()
-        using Documenter: doctest
-        using WackyOptions
-        doctest(WackyOptions)
-        include("docs/make.jl")'
-    - mkdir -p public
-    - mv docs/build public/dev
-  artifacts:
-    paths:
-      - public
-  only:
-    - master

test/fixtures/WackyOptions/README.md

@@ -1,4 +1,4 @@
-# WackyOptions [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://tester.gitlab.io/WackyOptions.jl/dev) [![Build Status](https://github.com/tester/WackyOptions.jl/workflows/CI/badge.svg)](https://github.com/tester/WackyOptions.jl/actions) [![Build Status](https://x.com/tester/WackyOptions.jl/badges/master/pipeline.svg)](https://x.com/tester/WackyOptions.jl/pipelines) [![Build Status](https://travis-ci.com/tester/WackyOptions.jl.svg?branch=master)](https://travis-ci.com/tester/WackyOptions.jl) [![Build Status](https://ci.appveyor.com/api/projects/status/github/tester/WackyOptions.jl?svg=true)](https://ci.appveyor.com/project/tester/WackyOptions-jl) [![Build Status](https://cloud.drone.io/api/badges/tester/WackyOptions.jl/status.svg)](https://cloud.drone.io/tester/WackyOptions.jl) [![Build Status](https://api.cirrus-ci.com/github/tester/WackyOptions.jl.svg)](https://cirrus-ci.com/github/tester/WackyOptions.jl) [![Coverage](https://codecov.io/gh/tester/WackyOptions.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/tester/WackyOptions.jl) [![Coverage](https://coveralls.io/repos/github/tester/WackyOptions.jl/badge.svg?branch=master)](https://coveralls.io/github/tester/WackyOptions.jl?branch=master)
+# WackyOptions [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://tester.github.io/WackyOptions.jl/stable) [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://tester.github.io/WackyOptions.jl/dev) [![Build Status](https://github.com/tester/WackyOptions.jl/workflows/CI/badge.svg)](https://github.com/tester/WackyOptions.jl/actions) [![Build Status](https://x.com/tester/WackyOptions.jl/badges/master/pipeline.svg)](https://x.com/tester/WackyOptions.jl/pipelines) [![Build Status](https://travis-ci.com/tester/WackyOptions.jl.svg?branch=master)](https://travis-ci.com/tester/WackyOptions.jl) [![Build Status](https://ci.appveyor.com/api/projects/status/github/tester/WackyOptions.jl?svg=true)](https://ci.appveyor.com/project/tester/WackyOptions-jl) [![Build Status](https://cloud.drone.io/api/badges/tester/WackyOptions.jl/status.svg)](https://cloud.drone.io/tester/WackyOptions.jl) [![Build Status](https://api.cirrus-ci.com/github/tester/WackyOptions.jl.svg)](https://cirrus-ci.com/github/tester/WackyOptions.jl) [![Coverage](https://codecov.io/gh/tester/WackyOptions.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/tester/WackyOptions.jl) [![Coverage](https://coveralls.io/repos/github/tester/WackyOptions.jl/badge.svg?branch=master)](https://coveralls.io/github/tester/WackyOptions.jl?branch=master)
 
 ## Citing
 

test/fixtures/WackyOptions/docs/make.jl

@@ -21,3 +21,8 @@ makedocs(;
     bar="baz",
     foo="bar",
 )
+
+deploydocs(;
+    repo="x.com/tester/WackyOptions.jl",
+    devbranch="foobar",
+)

test/interactive.jl

@@ -169,7 +169,7 @@ end
             print(
                 stdin.buffer,
                 DOWN^2, CR,      # Select GitLabCI
-                DOWN, CR, DONE,  # Customize index_md
+                DOWN^2, CR, DONE,  # Customize index_md
                 "x.txt", LF,     # Enter index file
             )
             @test PT.interactive(Documenter) == Documenter{GitLabCI}(; index_md="x.txt")

test/reference.jl

@@ -114,11 +114,12 @@ end
             Codecov(; file=STATIC_TXT),
             CompatHelper(; cron="0 0 */3 * *"),
             Coveralls(; file=STATIC_TXT),
-            Documenter{GitLabCI}(;
+            Documenter{GitHubActions}(;
                 assets=[STATIC_TXT],
                 logo=Logo(; light=STATIC_PNG),
                 makedocs_kwargs=Dict(:foo => "bar", :bar => "baz"),
                 canonical_url=(_t, _pkg) -> "http://example.com",
+                devbranch="foobar",
             ),
             DroneCI(; amd64=false, arm=true, arm64=true, extra_versions=["1.3"]),
             Git(; ignore=["a", "b", "c"], manifest=true),