Rename latest to dev, and add a symlink to not break links.

src/Documenter.jl

@@ -243,11 +243,12 @@ hide(root::AbstractString, children) = (true, nothing, root, map(hide, children)
         target = "site",
         repo   = "<required>",
         branch = "gh-pages",
-        latest = "master",
         osname = "linux",
         julia  = "<required>",
         deps   = <Function>,
         make   = <Function>,
+        devbranch = "master",
+        devurl = "dev",
     )
 
 Converts markdown files generated by [`makedocs`](@ref) to HTML and pushes them to `repo`.
@@ -266,7 +267,7 @@ deploydocs(
 
 When building the docs for a tag (i.e. a release) the documentation is deployed to
 a directory with the tag name (i.e. `vX.Y.Z`) and to the `stable` directory.
-Otherwise the docs are deployed to the `latest` directory.
+Otherwise the docs are deployed to the directory determined by the `devurl` argument.
 
 # Required keyword arguments
 
@@ -294,9 +295,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"`.
 
-**`latest`** is the branch that "tracks" the latest generated documentation. By default this
-value is set to `"master"`.
-
 **`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.
@@ -312,6 +310,12 @@ deps = Deps.pip("pygments", "mkdocs")
 **`make`** is the function used to convert the markdown files to HTML. By default this just
 runs `mkdocs build` which populates the `target` directory.
 
+**`devbranch`** is the branch that "tracks" the in-development version of the  generated
+documentation. By default this value is set to `"master"`.
+
+**`devurl`** the folder that in-development version of the docs will be deployed.
+Defaults to `"dev"`.
+
 # See Also
 
 The [Hosting Documentation](@ref) section of the manual provides a step-by-step guide to
@@ -325,14 +329,23 @@ function deploydocs(;
 
         repo   = error("no 'repo' keyword provided."),
         branch = "gh-pages",
-        latest = "master",
+        latest::Union{String,Nothing} = nothing, # deprecated
 
         osname = "linux",
         julia  = error("no 'julia' keyword provided."),
 
         deps   = Deps.pip("pygments", "mkdocs"),
         make   = () -> run(`mkdocs build`),
+
+        devbranch = "master",
+        devurl = "dev",
     )
+    # deprecation of latest kwarg (renamed to devbranch)
+    if latest !== nothing
+        Base.depwarn("The `latest` keyword argument have been renamed to `devbranch`.")
+        devbranch = latest
+        latest = nothing
+    end
 
     # Get environment variables.
     documenter_key      = get(ENV, "DOCUMENTER_KEY",       "")
@@ -371,7 +384,7 @@ function deploydocs(;
         travis_osname == osname &&
         travis_julia  == julia  &&
         (
-            travis_branch == latest ||
+            travis_branch == devbranch ||
             travis_tag    != ""
         )
 
@@ -401,7 +414,7 @@ function deploydocs(;
         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 \"$latest\" (kwarg: latest) or tag is set")
+        Utilities.debug("  deploying if branch equal to \"$devbranch\" (kwarg: devbranch) or tag is set")
         Utilities.debug("git commit SHA         = $sha")
         Utilities.debug("DOCUMENTER_KEY exists  = $(!isempty(documenter_key))")
         Utilities.debug("should_deploy          = $should_deploy")
@@ -429,7 +442,8 @@ function deploydocs(;
                 git_push(
                     root, temp, repo;
                     branch=branch, dirname=dirname, target=target,
-                    tag=travis_tag, key=documenter_key, sha=sha
+                    tag=travis_tag, key=documenter_key, sha=sha,
+                    devurl = devurl,
                 )
             end
         end
@@ -443,22 +457,22 @@ end
 """
     git_push(
         root, tmp, repo;
-        branch="gh-pages", dirname="", target="site", tag="", key="", sha=""
+        branch="gh-pages", dirname="", target="site", tag="", key="", sha="", devurl="dev"
     )
 
 Handles pushing changes to the remote documentation branch.
-When `tag` is empty the docs are deployed to the `latest` directory,
+When `tag` is empty the docs are deployed to the `devurl` directory,
 and when building docs for a tag they are deployed to a `vX.Y.Z` directory,
 and also to the `stable` directory.
 """
 function git_push(
         root, temp, repo;
-        branch="gh-pages", dirname="", target="site", tag="", key="", sha=""
+        branch="gh-pages", dirname="", target="site", tag="", key="", sha="", devurl="dev"
     )
     dirname = isempty(dirname) ? temp : joinpath(temp, dirname)
     isdir(dirname) || mkpath(dirname)
     # Versioned docs directories.
-    latest_dir = joinpath(dirname, "latest")
+    devurl_dir = joinpath(dirname, devurl)
     stable_dir = joinpath(dirname, "stable")
     tagged_dir = joinpath(dirname, tag)
 
@@ -500,10 +514,15 @@ function git_push(
                     run(`git commit --allow-empty -m "Initial empty commit for docs"`)
                 end
 
-                # Copy docs to `latest`, or `stable`, `<release>`, and `<version>` directories.
+                # Copy docs to `devurl`, or `stable`, `<release>`, and `<version>` directories.
                 if isempty(tag)
-                    gitrm_copy(target_dir, latest_dir)
-                    Writers.HTMLWriter.generate_siteinfo_file(latest_dir, "latest")
+                    gitrm_copy(target_dir, devurl_dir)
+                    Writers.HTMLWriter.generate_siteinfo_file(devurl_dir, devurl)
+                    # symlink "latest" to devurl to preserve links (remove in some future release)
+                    if devurl != "latest"
+                        rm(joinpath(dirname, "latest"); recursive = true, force = true)
+                        cd(dirname) do; symlink(devurl, "latest"); end
+                    end
                 else
                     @assert occursin(Base.VERSION_REGEX, tag) # checked in deploydocs
                     version = VersionNumber(tag)

src/Writers/HTMLWriter.jl

@@ -478,22 +478,23 @@ function render_topbar(ctx, navnode)
 end
 
 function generate_version_file(dir::AbstractString)
-    named_folders = []
-    tag_folders = []
-    for each in readdir(dir)
-        each in ("stable", "latest")         ? push!(named_folders,   each) :
-        occursin(Base.VERSION_REGEX, each)   ? push!(tag_folders,     each) : nothing
+    all_folders = readdir(dir)
+    folders = []
+
+    for each in all_folders
+        occursin(Base.VERSION_REGEX, each) && push!(folders, each)
     end
-    # put stable before latest
-    sort!(named_folders, rev = true)
     # sort tags by version number
-    sort!(tag_folders, lt = (x, y) -> VersionNumber(x) < VersionNumber(y), rev = true)
+    sort!(folders, lt = (x, y) -> VersionNumber(x) < VersionNumber(y), rev = true)
+
+    # include stable first, then dev
+    "dev"    in all_folders && pushfirst!(folders, "dev")
+    "stable" in all_folders && pushfirst!(folders, "stable")
+
     open(joinpath(dir, "versions.js"), "w") do buf
         println(buf, "var DOC_VERSIONS = [")
-        for group in (named_folders, tag_folders)
-            for folder in group
-                println(buf, "  \"", folder, "\",")
-            end
+        for folder in folders
+            println(buf, "  \"", folder, "\",")
         end
         println(buf, "];")
     end

test/htmlwriter.jl

@@ -21,7 +21,7 @@ import Documenter.Writers.HTMLWriter: jsescape, generate_version_file
     @test jsescape("policy to
 delete.") == "policy to\\u2028 delete."
 
     mktempdir() do tmpdir
-        versions = ["stable", "latest", "v0.2.6", "v0.1.1", "v0.1.0"]
+        versions = ["stable", "dev", "v0.2.6", "v0.1.1", "v0.1.0"]
         cd(tmpdir) do
             mkdir("foobar")
             for version in versions