From 5eb27492bd7ce23625ed67e3f8350fba5dda5f72 Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Sun, 19 Aug 2018 01:23:42 +0200 Subject: [PATCH] Rename latest to dev, and add a symlink to not break links. --- src/Documenter.jl | 51 +++++++++++++++++++++++++++------------ src/Writers/HTMLWriter.jl | 25 ++++++++++--------- test/htmlwriter.jl | 2 +- 3 files changed, 49 insertions(+), 29 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index 8b83efa78ef..e1c76aee414 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -243,11 +243,12 @@ hide(root::AbstractString, children) = (true, nothing, root, map(hide, children) target = "site", repo = "", branch = "gh-pages", - latest = "master", osname = "linux", julia = "", deps = , make = , + 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`, ``, and `` directories. + # Copy docs to `devurl`, or `stable`, ``, and `` 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) diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl index bc9b2e842f2..cb61afbc2d1 100644 --- a/src/Writers/HTMLWriter.jl +++ b/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 diff --git a/test/htmlwriter.jl b/test/htmlwriter.jl index a9dddd32692..4dea308d3cb 100644 --- a/test/htmlwriter.jl +++ b/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