Remove julia and osname kwarg from deploydocs

and recommend using Travis Build Stages instead.
JuliaDocs · Aug 30, 2018 · 722c095 · 722c095
1 parent 8d19e70
commit 722c095
Show file tree

Hide file tree

Showing 3 changed files with 59 additions and 45 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -51,7 +51,6 @@ makedocs(
 deploydocs(
     repo = "github.com/JuliaDocs/Documenter.jl.git",
     target = "build",
-    julia = "1.0",
     deps = nothing,
     make = nothing,
 )
diff --git a/docs/src/man/hosting.md b/docs/src/man/hosting.md
@@ -22,9 +22,10 @@ the docs you're currently reading.
 Once setup correctly the following will happen each time you push new updates to your
 package repository:
 
-- travis buildbots startup and run your tests;
-- each buildbot will build the package docs using your `docs/make.jl` script;
-- a single buildbot will then try to push the generated docs back to GitHub.
+- Travis buildbots startup and run your tests in a test stage;
+- after the test stage a single bot will start a new "deploy docs" stage;
+- if the building is successful the bot will try to push the generated
+  docs back to GitHub.
 
 Note that the hosted documentation does not update when you make pull
 requests; you see updates only when you merge to `master` or push new tags.
@@ -97,15 +98,43 @@ Follow the instructions that are printed out, namely:
 
 ## `.travis.yml` Configuration
 
-In the `after_success` section of the `.travis.yml` file, where code coverage is processed,
-run your `docs/make.jl` file:
+To tell Travis that we want a new build stage we can add the following to the
+`.travis.yml` file:
 
 ```yaml
-after_success:
-  - julia -e 'Pkg.add("Documenter")'
-  - julia -e 'cd(Pkg.dir("PACKAGE_NAME")); include(joinpath("docs", "make.jl"))'
+jobs:
+  include:
+    - stage: "Deploy docs"
+      julia: 1.0
+      os: linux
+      script:
+        - julia --project=docs/ -e 'using Pkg; Pkg.instantiate()'
+        - julia --project=docs/ -e 'using Pkg; Pkg.add(PackageSpec(path=pwd()))'
+        - julia --project=docs/ docs/make.jl
+      after_success: skip
 ```
 
+where the `julia:` and `os:` entries decide the worker from which the docs
+are built and deployed. In the example above we will thus build and deploy
+the documentation from a linux worker running Julia 1.0.
+For more information on how to setup a build stage,
+see the Travis manual for [Build Stages](https://docs.travis-ci.com/user/build-stages).
+
+The three lines in the `script:` section does the following:
+ 1. Instantiate the doc-building environment (i.e. `docs/Project.toml`, see below).
+ 2. Install your package in the doc-build environment.
+ 3. Run the docs/make.jl script, which builds and deploys the documentation.
+
+The doc-build environment `docs/Project.toml` includes Documenter
+and other doc-build dependencies your package might have.
+If Documenter is the only dependency, then the `Project.toml`
+should include the following:
+```toml
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+```
+
+
 ## The `deploydocs` Function
 
 At the moment your `docs/make.jl` file probably only contains
@@ -123,37 +152,24 @@ Add the following at the end of the file:
 ```julia
 deploydocs(
     repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git",
-    julia = "1.0"
 )
 ```
 
 where `USER_NAME` and `PACKAGE_NAME` must be set to the appropriate names.
 Note that `repo` should not specify any protocol, i.e. it should not begin with `https://`
 or `git@`.
 
-Since you are probably testing your package on against multiple Julia versions and on
-multiple operating systems, you need to specify which of those builds should be used for
-deployment. This is to avoid deploying the same docs multiple times.
-
-The mandatory `julia` keyword argument specifies the Julia version and must be one from
-the `julia:` section of your `.travis.yml`.
-The operating system defaults to Linux, but can be changed using the `osname` keyword
-as follows:
+The keyword `deps` serves to provide the required dependencies to deploy
+the documentation:
 
 ```julia
 deploydocs(
     deps   = Deps.pip("mkdocs", "python-markdown-math"),
     repo   = "github.com/USER_NAME/PACKAGE_NAME.jl.git",
-    julia  = "nightly",
-    osname = "osx"
 )
 ```
 
-This will deploy the docs from the OSX Julia nightly Travis build bot.
-
-The keyword `deps` serves to provide the required dependencies to deploy
-the documentation. In the example above we include the dependencies
-[mkdocs](https://www.mkdocs.org)
+In the example above we include the dependencies [mkdocs](https://www.mkdocs.org)
 and [`python-markdown-math`](https://github.com/mitya57/python-markdown-math).
 The former makes sure that MkDocs is installed to deploy the documentation,
 and the latter provides the `mdx_math` markdown extension to exploit MathJax

diff --git a/src/Documenter.jl b/src/Documenter.jl
@@ -242,8 +242,6 @@ hide(root::AbstractString, children) = (true, nothing, root, map(hide, children)
         target = "site",
         repo   = "<required>",
         branch = "gh-pages",
-        osname = "linux",
-        julia  = "<required>",
         deps   = <Function>,
         make   = <Function>,
         devbranch = "master",
@@ -271,10 +269,6 @@ Otherwise the docs are deployed to the directory determined by the `devurl` argu
 
 # Required keyword arguments
 
-**`julia`** is the version of Julia that will be used to deploy generated documentation.
-This value must be one of those specified in the `julia:`
-section of the `.travis.yml` configuration file.
-
 **`repo`** is the remote repository where generated HTML content should be pushed to. Do not
 specify any protocol - "https://" or "git@" should not be present. This keyword *must*
 be set and will throw an error when left undefined. For example this package uses the
@@ -295,10 +289,6 @@ default value is `"site"`.
 **`branch`** is the branch where the generated documentation is pushed. If the branch does
 not exist, a new orphaned branch is created automatically. It defaults to `"gh-pages"`.
 
-**`osname`** is the operating system which will be used to deploy generated documentation.
-This defaults to `"linux"`. This value must be one of those specified in the `os:` section
-of the `.travis.yml` configuration file.
-
 **`deps`** is the function used to install any dependencies needed to build the
 documentation. By default this function installs `pygments` and `mkdocs` using the
 [`Deps.pip`](@ref) function:
@@ -345,8 +335,8 @@ function deploydocs(;
         branch = "gh-pages",
         latest::Union{String,Nothing} = nothing, # deprecated
 
-        osname = "linux",
-        julia  = error("no 'julia' keyword provided."),
+        osname::Union{String,Nothing} = nothing, # deprecated
+        julia::Union{String,Nothing} = nothing, # deprecated
 
         deps   = Deps.pip("pygments", "mkdocs"),
         make   = () -> run(`mkdocs build`),
@@ -361,15 +351,30 @@ function deploydocs(;
         devbranch = latest
         @info("setting `devbranch` to `$(devbranch)`.")
     end
+    # deprecation/removal of `julia` and `osname` kwargs
+    if julia !== nothing
+        Base.depwarn("the `julia` keyword argument to `Documenter.deploydocs` is " *
+            "removed. Use Travis Build Stages for determining from where to deploy instead, " *
+            "see the section about Hosting in the Documenter manual.", :deploydocs)
+    end
+    if osname !== nothing
+        Base.depwarn("the `osname` keyword argument to `Documenter.deploydocs` is " *
+            "removed. Use Travis Build Stages for determining from where to deploy instead, " *
+            "see the section about Hosting in the Documenter manual.", :deploydocs)
+    end
+    travis_julia = get(ENV, "TRAVIS_JULIA_VERSION", "")
+    travis_osname = get(ENV, "TRAVIS_OS_NAME","")
+    if !(julia == travis_julia && osname == travis_osname)
+        @info("skipping docs deployment.")
+    end
 
     # Get environment variables.
     documenter_key      = get(ENV, "DOCUMENTER_KEY",       "")
     travis_branch       = get(ENV, "TRAVIS_BRANCH",        "")
     travis_pull_request = get(ENV, "TRAVIS_PULL_REQUEST",  "")
     travis_repo_slug    = get(ENV, "TRAVIS_REPO_SLUG",     "")
     travis_tag          = get(ENV, "TRAVIS_TAG",           "")
-    travis_osname       = get(ENV, "TRAVIS_OS_NAME",       "")
-    travis_julia        = get(ENV, "TRAVIS_JULIA_VERSION", "")
+
 
     # Other variables.
     sha = cd(root) do
@@ -396,8 +401,6 @@ function deploydocs(;
     should_deploy =
         occursin(travis_repo_slug, repo) &&
         travis_pull_request == "false"   &&
-        travis_osname == osname &&
-        travis_julia  == julia  &&
         (
             travis_branch == devbranch ||
             travis_tag    != ""
@@ -423,10 +426,6 @@ function deploydocs(;
         Utilities.debug("  should match \"$repo\" (kwarg: repo)")
         Utilities.debug("TRAVIS_PULL_REQUEST    = \"$travis_pull_request\"")
         Utilities.debug("  deploying if equal to \"false\"")
-        Utilities.debug("TRAVIS_OS_NAME         = \"$travis_osname\"")
-        Utilities.debug("  deploying if equal to \"$osname\" (kwarg: osname)")
-        Utilities.debug("TRAVIS_JULIA_VERSION   = \"$travis_julia\"")
-        Utilities.debug("  deploying if equal to \"$julia\" (kwarg: julia)")
         Utilities.debug("TRAVIS_BRANCH          = \"$travis_branch\"")
         Utilities.debug("TRAVIS_TAG             = \"$travis_tag\"")
         Utilities.debug("  deploying if branch equal to \"$devbranch\" (kwarg: devbranch) or tag is set")