Merge pull request #44 from invenia/cdg/documenter

Use the new Documenter build/deploy workflow

.travis.yml

@@ -3,7 +3,6 @@ os:
   - linux
   - osx
 julia:
-  - 0.7
   - 1.0
   - nightly
 matrix:
@@ -12,10 +11,14 @@ matrix:
   fast_finish: true
 notifications:
   email: false
-after_success:
+after_success: julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
-  - julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; CodeCov.submit(process_folder())'
+jobs:
-  # For package generation examples.
+  include:
-  - git config --global user.name "Travis"
+    - stage: Documentation
-  - git config --global user.email "travis@c.i"
+      julia: 1.0
-  - git config --global github.user "travis"
+      script: julia --project=docs -e '
-  - julia -e 'using Pkg; ps=Pkg.PackageSpec(name="Documenter", version="0.19"); Pkg.add(ps); Pkg.pin(ps); include(joinpath("docs", "make.jl"))'
+          using Pkg;
+          Pkg.develop(PackageSpec(path=pwd()));
+          Pkg.instantiate();
+          include("docs/make.jl");'
+      after_success: skip

Manifest.toml

@@ -37,9 +37,9 @@ uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
 
 [[Mustache]]
 deps = ["Tables", "Test"]
-git-tree-sha1 = "536782063c50421b05d1369bbd09fced13624361"
+git-tree-sha1 = "be8d12b4a84ed7b592a6540b71c664440a4dd7f1"
 uuid = "ffc61752-8dc7-55ee-8c37-f3e9cdd09e70"
-version = "0.5.7"
+version = "0.5.8"
 
 [[Pkg]]
 deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
@@ -74,9 +74,9 @@ uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
 
 [[Tables]]
 deps = ["Requires", "Test"]
-git-tree-sha1 = "c7fb447deab835fa70ce6717e78c68b0f466a42c"
+git-tree-sha1 = "940944e6b68a35046282897a2218891c7cf14a32"
 uuid = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
-version = "0.1.11"
+version = "0.1.12"
 
 [[Test]]
 deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]

Project.toml

@@ -1,7 +1,7 @@
 name = "PkgTemplates"
 uuid = "14b8a8f1-9102-5b29-a752-f990bacb7fe1"
 authors = ["Chris de Graaf <chrisadegraaf@gmail.com>"]
-version = "0.3.0"
+version = "0.4.1"
 
 [deps]
 AutoHashEquals = "15f4f7f2-30c1-5605-9d31-71845cf9641f"

README.md

@@ -12,7 +12,7 @@ repeatable, and customizable way.**
 ## Installation
 
 ```julia
-(v1.0) pkg> add PkgTemplates
+pkg> add PkgTemplates
 ```
 
 ## Usage
@@ -30,33 +30,10 @@ Template:
   → Package directory: ~/.julia/dev
   → Minimum Julia version: v1.0
   → SSH remote: No
+  → Commit Manifest.toml: No
   → Plugins: None
 
 julia> generate("MyPkg", t)
-Generating project MyPkg:
-    /Users/degraafc/.julia/dev/MyPkg/Project.toml
-    /Users/degraafc/.julia/dev/MyPkg/src/MyPkg.jl
-[ Info: Initialized git repo at /Users/degraafc/.julia/dev/MyPkg
-[ Info: Set remote origin to https://github.com/myusername/MyPkg.jl
-  Updating registry at `~/.julia/registries/General`
-  Updating git-repo `https://github.com/JuliaRegistries/General.git`
- Resolving package versions...
-  Updating `~/.julia/dev/MyPkg/Project.toml`
-  [8dfed614] + Test
-  Updating `~/.julia/dev/MyPkg/Manifest.toml`
-  [2a0f44e3] + Base64
-  [8ba89e20] + Distributed
-  [b77e0a4c] + InteractiveUtils
-  [8f399da3] + Libdl
-  [37e2e46d] + LinearAlgebra
-  [56ddb016] + Logging
-  [d6f4376e] + Markdown
-  [9a3f8284] + Random
-  [9e88b42a] + Serialization
-  [6462fe0b] + Sockets
-  [8dfed614] + Test
-[ Info: Staged and committed 8 files/directories: src/, Project.toml, Manifest.toml, test/, REQUIRE, README.md, .gitignore, LICENSE
-[ Info: Finished
 
 julia> run(`git -C $(joinpath(t.dir, "MyPkg")) ls-files`);
 .gitignore
@@ -76,7 +53,7 @@ julia> t = Template(;
            user="myusername",
            license="ISC",
            authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
-           dir=joinpath(homedir(), "code"),
+           dir="~/code",
            julia_version=v"0.7",
            plugins=[
                TravisCI(),
@@ -93,6 +70,7 @@ Template:
   → Package directory: ~/code
   → Minimum Julia version: v0.7
   → SSH remote: No
+  → Commit Manifest.toml: No
   → Plugins:
     • AppVeyor:
       → Config file: Default
@@ -111,40 +89,17 @@ Template:
       → 0 gitignore entries
 
 julia> generate(t, "MyPkg2")
-Generating project MyPkg2:
-    /Users/degraafc/code/MyPkg2/Project.toml
-    /Users/degraafc/code/MyPkg2/src/MyPkg2.jl
-[ Info: Initialized git repo at /Users/degraafc/code/MyPkg2
-[ Info: Set remote origin to https://github.com/myusername/MyPkg2.jl
-[ Info: Created empty gh-pages branch
- Resolving package versions...
-  Updating `~/code/MyPkg2/Project.toml`
-  [8dfed614] + Test
-  Updating `~/code/MyPkg2/Manifest.toml`
-  [2a0f44e3] + Base64
-  [8ba89e20] + Distributed
-  [b77e0a4c] + InteractiveUtils
-  [8f399da3] + Libdl
-  [37e2e46d] + LinearAlgebra
-  [56ddb016] + Logging
-  [d6f4376e] + Markdown
-  [9a3f8284] + Random
-  [9e88b42a] + Serialization
-  [6462fe0b] + Sockets
-  [8dfed614] + Test
-[ Info: Staged and committed 11 files/directories: src/, Project.toml, Manifest.toml, test/, REQUIRE, README.md, .gitignore, LICENSE, .appveyor.yml, .travis.yml, docs/
-[ Info: Finished
-[ Info: Remember to push all created branches to your remote: git push --all
 
 julia> run(`git -C $(joinpath(t.dir, "MyPkg2")) ls-files`);
 .appveyor.yml
 .gitignore
 .travis.yml
 LICENSE
-Manifest.toml
 Project.toml
 README.md
 REQUIRE
+docs/Manifest.toml
+docs/Project.toml
 docs/make.jl
 docs/src/index.md
 src/MyPkg2.jl

defaults/travis.yml

@@ -12,7 +12,7 @@ matrix:
   fast_finish: true
 notifications:
   email: false
-{{#AFTER}}
+{{#COVERAGE}}
 after_success:
 {{#CODECOV}}
   - julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
@@ -20,7 +20,16 @@ after_success:
 {{#COVERALLS}}
   - julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Coveralls.submit(process_folder())'
 {{/COVERALLS}}
+{{/COVERAGE}}
 {{#DOCUMENTER}}
-  - julia -e 'if VERSION >= v"0.7.0"; using Pkg; ps=Pkg.PackageSpec(name="Documenter", version="0.19"); Pkg.add(ps); Pkg.pin(ps); else; Pkg.add("Documenter"); end; include(joinpath("docs", "make.jl"))'
+jobs:
+  include:
+    - stage: Documentation
+      julia: {{VERSION}}
+      script: julia --project=docs -e '
+          using Pkg;
+          Pkg.develop(PackageSpec(path=pwd()));
+          Pkg.instantiate();
+          include("docs/make.jl");'
+      after_success: skip
 {{/DOCUMENTER}}
-{{/AFTER}}

docs/Manifest.toml

@@ -0,0 +1,79 @@
+[[Base64]]
+uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+
+[[Dates]]
+deps = ["Printf"]
+uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
+
+[[Distributed]]
+deps = ["LinearAlgebra", "Random", "Serialization", "Sockets"]
+uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
+
+[[DocStringExtensions]]
+deps = ["LibGit2", "Markdown", "Pkg", "Test"]
+git-tree-sha1 = "1df01539a1c952cef21f2d2d1c092c2bcf0177d7"
+uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+version = "0.6.0"
+
+[[Documenter]]
+deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "LibGit2", "Logging", "Markdown", "Pkg", "REPL", "Random", "Test", "Unicode"]
+git-tree-sha1 = "a6db1c69925cdc53aafb38caec4446be26e0c617"
+uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+version = "0.21.0"
+
+[[InteractiveUtils]]
+deps = ["LinearAlgebra", "Markdown"]
+uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+
+[[LibGit2]]
+uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
+
+[[Libdl]]
+uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
+
+[[LinearAlgebra]]
+deps = ["Libdl"]
+uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+
+[[Logging]]
+uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
+
+[[Markdown]]
+deps = ["Base64"]
+uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
+
+[[Pkg]]
+deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
+uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+
+[[Printf]]
+deps = ["Unicode"]
+uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+
+[[REPL]]
+deps = ["InteractiveUtils", "Markdown", "Sockets"]
+uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+
+[[Random]]
+deps = ["Serialization"]
+uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+
+[[SHA]]
+uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"
+
+[[Serialization]]
+uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+
+[[Sockets]]
+uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
+
+[[Test]]
+deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
+uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[[UUIDs]]
+deps = ["Random"]
+uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+
+[[Unicode]]
+uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -2,7 +2,7 @@ using Documenter, PkgTemplates
 
 makedocs(;
     modules=[PkgTemplates],
-    format=:html,
+    format=Documenter.HTML(),
     pages=[
         "Home" => "index.md",
         "Package Generation" => "pages/package_generation.md",
@@ -19,8 +19,4 @@ makedocs(;
 
 deploydocs(;
     repo="github.com/invenia/PkgTemplates.jl",
-    target="build",
-    julia="1.0",
-    deps=nothing,
-    make=nothing,
 )

docs/src/index.md

@@ -12,14 +12,23 @@ repeatable, and customizable way.**
 ## Installation
 
 ```julia
-(v1.0) pkg> add PkgTemplates
+pkg> add PkgTemplates
 ```
 
 ## Usage
 
+```@setup usage
+run(`git config --global user.name "Travis"`)
+run(`git config --global user.email "travis@c.i"`)
+run(`git config --global github.user "travis"`)
+using Pkg
+Pkg.activate(mktempdir())
+```
+
 The simplest template requires no arguments.
 
-```@repl
+
+```@repl usage
 using PkgTemplates
 t = Template()
 generate("MyPkg", t)
@@ -29,13 +38,13 @@ run(`git -C $(joinpath(t.dir, "MyPkg")) ls-files`);
 However, we can also configure a number of keyword arguments to
 [`Template`](@ref):
 
-```@repl
+```@repl usage
 using PkgTemplates
 t = Template(;
     user="myusername",
     license="MIT",
     authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
-    dir=joinpath(homedir(), "code"),
+    dir="~/code",
     julia_version=v"0.7",
     ssh=true,
     plugins=[

src/generate.jl

@@ -230,7 +230,7 @@ Returns an array of generated file/directory names.
 function gen_gitignore(pkg_dir::AbstractString, t::Template)
     pkg = basename(pkg_dir)
     seen = [".DS_Store"]
-    t.manifest || push!(seen, "Manifest.toml")
+    t.manifest || push!(seen, "/Manifest.toml")  # Only ignore manifests at the repo root.
     patterns = vcat(map(p -> p.gitignore, values(t.plugins))...)
     for pattern in patterns
         if !in(pattern, seen)

src/plugins/documenter.jl

@@ -20,14 +20,23 @@ abstract type Documenter <: CustomPlugin end
 
 function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString)
     path = joinpath(t.dir, pkg_name)
-    docs_dir = joinpath(path, "docs", "src")
+    docs_dir = joinpath(path, "docs")
     mkpath(docs_dir)
 
+    # Create the documentation project.
+    proj = Base.current_project()
+    try
+        Pkg.activate(docs_dir)
+        Pkg.add("Documenter")
+    finally
+        proj === nothing ? Pkg.activate() : Pkg.activate(proj)
+    end
+
     tab = repeat(" ", 4)
     assets_string = if !isempty(p.assets)
-        mkpath(joinpath(docs_dir, "assets"))
+        mkpath(joinpath(docs_dir, "src", "assets"))
         for file in p.assets
-            cp(file, joinpath(docs_dir, "assets", basename(file)))
+            cp(file, joinpath(docs_dir, "src", "assets", basename(file)))
         end
 
         # We want something that looks like the following:
@@ -55,7 +64,7 @@ function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString)
         kws = [keys(p.additional_kwargs)...]
         valid_keys = filter(k -> !in(Symbol(k), STANDARD_KWS), kws)
         if length(p.additional_kwargs) > length(valid_keys)
-            invalid_keys = filter(k -> in(Symbol(k), STANDARD_KWS), kws)
+            invalid_keys = filter(k -> Symbol(k) in STANDARD_KWS, kws)
             @warn string(
                 "Ignoring predefined Documenter kwargs ",
                 join(map(repr, invalid_keys), ", "),
@@ -72,7 +81,7 @@ function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString)
 
         makedocs(;
             modules=[$pkg_name],
-            format=:html,
+            format=Documenter.HTML(),
             pages=[
                 "Home" => "index.md",
             ],
@@ -93,8 +102,8 @@ function gen_plugin(p::Documenter, t::Template, pkg_name::AbstractString)
     ```
     """
 
-    gen_file(joinpath(dirname(docs_dir), "make.jl"), make)
+    gen_file(joinpath(docs_dir, "make.jl"), make)
-    gen_file(joinpath(docs_dir, "index.md"), docs)
+    gen_file(joinpath(docs_dir, "src", "index.md"), docs)
 end
 
 function Base.show(io::IO, p::Documenter)

src/plugins/githubpages.jl

@@ -7,6 +7,11 @@ adds appropriate badges to the README, and updates the `.gitignore` accordingly.
 
 # Keyword Arguments
 * `assets::Vector{<:AbstractString}=String[]`: Array of paths to Documenter asset files.
+
+!!! note
+    If deploying documentation with Travis CI, don't forget to complete the required
+    configuration (see
+    [here](https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#SSH-Deploy-Keys-1)).
 """
 @auto_hash_equals struct GitHubPages <: Documenter
     gitignore::Vector{AbstractString}
@@ -50,10 +55,6 @@ function gen_plugin(p::GitHubPages, t::Template, pkg_name::AbstractString)
 
                 deploydocs(;
                     repo="$(t.host)/$(t.user)/$pkg_name.jl",
-                    target="build",
-                    julia="1.0",
-                    deps=nothing,
-                    make=nothing,
                 )
                 """
             )

test/plugins/travisci.jl

@@ -37,7 +37,7 @@ pkg_dir = joinpath(t.dir, test_pkg)
         @test !occursin("after_success", travis)
         @test !occursin("Codecov.submit", travis)
         @test !occursin("Coveralls.submit", travis)
-        @test !occursin("Pkg.add(\"Documenter\")", travis)
+        @test !occursin("stage: Documentation", travis)
         rm(joinpath(pkg_dir, ".travis.yml"))
 
         # Generating the plugin with Codecov in the template should create a post-test step.
@@ -48,7 +48,7 @@ pkg_dir = joinpath(t.dir, test_pkg)
         @test occursin("after_success", travis)
         @test occursin("Codecov.submit", travis)
         @test !occursin("Coveralls.submit", travis)
-        @test !occursin("Pkg.add(\"Documenter\")", travis)
+        @test !occursin("stage: Documentation", travis)
         rm(joinpath(pkg_dir, ".travis.yml"))
 
         # Coveralls should do the same.
@@ -59,7 +59,7 @@ pkg_dir = joinpath(t.dir, test_pkg)
         @test occursin("after_success", travis)
         @test occursin("Coveralls.submit", travis)
         @test !occursin("Codecov.submit", travis)
-        @test !occursin("Pkg.add(\"Documenter\")", travis)
+        @test !occursin("stage: Documentation", travis)
         rm(joinpath(pkg_dir, ".travis.yml"))
 
         # With a Documenter plugin, there should be a docs deployment step.
@@ -68,7 +68,7 @@ pkg_dir = joinpath(t.dir, test_pkg)
         delete!(t.plugins, GitHubPages)
         travis = read(joinpath(pkg_dir, ".travis.yml"), String)
         @test occursin("after_success", travis)
-        @test occursin("Pkg.add(\"Documenter\")", travis)
+        @test occursin("stage: Documentation", travis)
         @test !occursin("Codecov.submit", travis)
         @test !occursin("Coveralls.submit", travis)
         rm(joinpath(pkg_dir, ".travis.yml"))

test/tests.jl

@@ -463,7 +463,7 @@ end
         @test occursin("\n    checkdocs=:none,\n", make)
 
         @test !occursin("format=:markdown", make)
-        @test occursin("format=:html", make)
+        @test occursin("format=Documenter.HTML()", make)
         rm(pkg_dir; recursive=true)
     end
     # Test with string kwargs