Skip to content

Commit

Permalink
Rename latest to dev, and add a symlink to not break links. (#802)
Browse files Browse the repository at this point in the history
  • Loading branch information
@fredrikekre
fredrikekre authored Aug 20, 2018
1 parent c58e7e0 commit 924d99b
Show file tree
Hide file tree
Showing 3 changed files with 52 additions and 29 deletions.
54 changes: 38 additions & 16 deletions src/Documenter.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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 has been renamed to `devbranch`.")
devbranch = latest
@info("setting `devbranch` to `$(devbranch)`.")
end

# Get environment variables.
documenter_key = get(ENV, "DOCUMENTER_KEY", "")
Expand Down Expand Up @@ -371,7 +384,7 @@ function deploydocs(;
travis_osname == osname &&
travis_julia == julia &&
(
travis_branch == latest ||
travis_branch == devbranch ||
travis_tag != ""
)

Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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
Expand All @@ -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)

Expand Down Expand Up @@ -500,10 +514,18 @@ 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)
@warn(string("creating symlink from `latest` to `$(devurl)` for backwards ",
"compatibility with old links. In future Documenter versions this symlink ",
"will not be created. Please update any links that point to `latest`."))
cd(dirname) do; symlink(devurl, "latest"); end
end
else
@assert occursin(Base.VERSION_REGEX, tag) # checked in deploydocs
version = VersionNumber(tag)
Expand Down
25 changes: 13 additions & 12 deletions src/Writers/HTMLWriter.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion test/htmlwriter.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 924d99b

Please sign in to comment.