Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rename latest to dev. #802

Merged
merged 1 commit into from
Aug 20, 2018
Merged

Rename latest to dev. #802

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 38 additions & 16 deletions src/Documenter.jl
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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