Merge pull request #44 from invenia/cdg/documenter

Use the new Documenter build/deploy workflow
2018-12-19 14:30:15 -06:00 · 2018-12-19 14:30:15 -06:00 · 95555df86f
commit 95555df86f
parent 44a03f1a5d 35b42be06c
14 changed files with 156 additions and 93 deletions
--- a/.travis.yml
+++ b/.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:
-  - julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; CodeCov.submit(process_folder())'
-  # For package generation examples.
-  - git config --global user.name "Travis"
-  - git config --global user.email "travis@c.i"
-  - git config --global github.user "travis"
-  - julia -e 'using Pkg; ps=Pkg.PackageSpec(name="Documenter", version="0.19"); Pkg.add(ps); Pkg.pin(ps); include(joinpath("docs", "make.jl"))'
+after_success: julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
+jobs:
+  include:
+    - stage: Documentation
+      julia: 1.0
+      script: julia --project=docs -e '
+          using Pkg;
+          Pkg.develop(PackageSpec(path=pwd()));
+          Pkg.instantiate();
+          include("docs/make.jl");'
+      after_success: skip
--- a/Manifest.toml
+++ b/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"]
--- a/Project.toml
+++ b/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"
--- a/README.md
+++ b/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
--- a/defaults/travis.yml
+++ b/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}}
--- a/docs/Manifest.toml
+++ b/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"
--- a/docs/Project.toml
+++ b/docs/Project.toml
@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
--- a/docs/make.jl
+++ b/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,
 )
--- a/docs/src/index.md
+++ b/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=[
--- a/src/generate.jl
+++ b/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)
--- a/src/plugins/documenter.jl
+++ b/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, "index.md"), docs)
+    gen_file(joinpath(docs_dir, "make.jl"), make)
+    gen_file(joinpath(docs_dir, "src", "index.md"), docs)
 end

 function Base.show(io::IO, p::Documenter)
--- a/src/plugins/githubpages.jl
+++ b/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,
                )
                """
            )
--- a/test/plugins/travisci.jl
+++ b/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"))
--- a/test/tests.jl
+++ b/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