From 2f9f705fe69b104ab5fb2315e796cec258b8a136 Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Mon, 3 Sep 2018 08:48:01 +0200 Subject: [PATCH] Remove julia and osname kwarg from deploydocs and recommend using Travis Build Stages instead. --- .travis.yml | 2 +- docs/make.jl | 1 - docs/src/man/hosting.md | 67 ++++++++++++++++++++++++++--------------- src/Documenter.jl | 38 +++++++++++------------ 4 files changed, 62 insertions(+), 46 deletions(-) diff --git a/.travis.yml b/.travis.yml index ddf61ba76e..30919cd94d 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,7 +18,7 @@ after_success: jobs: include: - - stage: "Deploy docs" + - stage: "Documentation" julia: 1.0 os: linux script: diff --git a/docs/make.jl b/docs/make.jl index f118bd3f6d..84e7b89288 100644 --- 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 index 3f578e943d..bc5f210125 100644 --- 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,46 @@ 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: "Documentation" + 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" + +[compat] +Documenter = "0.20" +``` + + ## The `deploydocs` Function At the moment your `docs/make.jl` file probably only contains @@ -123,7 +155,6 @@ Add the following at the end of the file: ```julia deploydocs( repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git", - julia = "1.0" ) ``` @@ -131,29 +162,17 @@ 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 index 1cc8aaf0d3..82d8a3edf7 100644 --- 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 = "", branch = "gh-pages", - osname = "linux", - julia = "", deps = , make = , 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,6 +351,21 @@ 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 for more details.", :deploydocs) + @info("skipping docs deployment.") + return + 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 for more details.", :deploydocs) + @info("skipping docs deployment.") + return + end # Get environment variables. documenter_key = get(ENV, "DOCUMENTER_KEY", "") @@ -368,8 +373,7 @@ function deploydocs(; 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 +400,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 +425,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")