From 3d50c1d79ea30100d9d2ccda73cd4dbc7b673df3 Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Tue, 29 Jun 2021 13:07:14 +0200 Subject: [PATCH] Support deployment to the root instead of to a version subfolder, fixes #1615. (#1616) --- CHANGELOG.md | 4 +++ docs/src/man/hosting.md | 26 +++++++++++++++- src/Documenter.jl | 68 +++++++++++++++++++++++++++-------------- src/deployconfig.jl | 4 ++- 4 files changed, 77 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 89855cf70e..83a71c3658 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Version `v0.27.3` +* ![Feature][badge-feature] Documenter can now deploy documentation directly to the "root" instead of versioned folders. ([#1615][github-1615], [#1616][github-1616]) + * ![Enhancement][badge-enhancement] The version of Documenter used for generating a document is now displayed in the build information. ([#1609][github-1609], [#1611][github-1611]) * ![Bugfix][badge-bugfix] The HTML front end no longer uses ligatures when displaying code (with JuliaMono). ([#1610][github-1610], [#1617][github-1617]) @@ -838,6 +840,8 @@ [github-1609]: https://github.com/JuliaDocs/Documenter.jl/pull/1609 [github-1610]: https://github.com/JuliaDocs/Documenter.jl/issues/1610 [github-1611]: https://github.com/JuliaDocs/Documenter.jl/pull/1611 +[github-1615]: https://github.com/JuliaDocs/Documenter.jl/issues/1615 +[github-1616]: https://github.com/JuliaDocs/Documenter.jl/pull/1616 [github-1617]: https://github.com/JuliaDocs/Documenter.jl/pull/1617 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079 diff --git a/docs/src/man/hosting.md b/docs/src/man/hosting.md index d3d3467396..b5be35c54b 100644 --- a/docs/src/man/hosting.md +++ b/docs/src/man/hosting.md @@ -413,7 +413,12 @@ _This workflow was taken from [CliMA/TimeMachine.jl](https://github.com/CliMA/Ti ## Documentation Versions -The documentation is deployed as follows: +!!! note + This section describes the default mode of deployment, which is by version. + See the following section on [Deploying without the versioning scheme](@ref) + if you want to deploy directly to the "root". + +By default the documentation is deployed as follows: - Documentation built for a tag `vX.Y.Z` will be stored in a folder `vX.Y.Z`. @@ -473,6 +478,25 @@ and text of the image can be changed by altering `docs-stable-blue` as described standard to make it easier for potential users to find documentation links across multiple package README files. +### Deploying without the versioning scheme + +Documenter supports deployment directly to the website root ignoring any version +subfolders as described in the previous section. This can be useful if you use +Documenter for something that is not a versioned project, for example. +To do this, pass `versions = nothing` to the [`deploydocs`](@ref) function. +Now the pages should be found directly at + +``` +https://USER_NAME.github.io/PACKAGE_NAME.jl/ +``` + +Preview builds are still deployed to the `previews` subfolder. + +!!! note + The landing page for the [JuliaDocs GitHub organization](https://juliadocs.github.io) + ([source repository](https://github.com/JuliaDocs/juliadocs.github.io)) is one example + where this functionality is used. + --- **Final Remarks** diff --git a/src/Documenter.jl b/src/Documenter.jl index dea21f64c6..57c2215a4f 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -409,6 +409,9 @@ the generated html. The following entries are valid in the `versions` vector: and generate a url from which `"second"` can be accessed. The second argument can be `"v^"`, to point to the maximum version docs (as in e.g. `"stable" => "v^"`). +If `versions = nothing` documentation will be deployed directly to the "root", i.e. +not to a versioned subfolder. See the manual section on +[Deploying without the versioning scheme](@ref) for more details. **`push_preview`** a boolean that specifies if preview documentation should be deployed from pull requests or not. If your published documentation is hosted @@ -481,6 +484,11 @@ function deploydocs(; deploy_subfolder = deploy_decision.subfolder deploy_is_preview = deploy_decision.is_preview + # Non-versioned docs: deploy to root + if versions === nothing && !deploy_is_preview + deploy_subfolder = nothing + end + # Add local bin path if needed. Deps.updatepath!() # Install dependencies when applicable. @@ -585,26 +593,30 @@ function git_push( end # Copy docs to `subfolder` directory. - deploy_dir = joinpath(dirname, subfolder) + deploy_dir = subfolder === nothing ? dirname : joinpath(dirname, subfolder) gitrm_copy(target_dir, deploy_dir) - Writers.HTMLWriter.generate_siteinfo_file(deploy_dir, subfolder) - - # Expand the users `versions` vector - entries, symlinks = Writers.HTMLWriter.expand_versions(dirname, versions) - - # Create the versions.js file containing a list of `entries`. - # This must always happen after the folder copying. - Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries, symlinks) - - # generate the symlinks, make sure we don't overwrite devurl - cd(dirname) do - for kv in symlinks - i = findfirst(x -> x.first == devurl, symlinks) - if i === nothing - rm_and_add_symlink(kv.second, kv.first) - else - throw(ArgumentError(string("link `$(kv)` cannot overwrite ", - "`devurl = $(devurl)` with the same name."))) + + if versions !== nothing + # Generate siteinfo-file with DOCUMENTER_CURRENT_VERSION + Writers.HTMLWriter.generate_siteinfo_file(deploy_dir, subfolder) + + # Expand the users `versions` vector + entries, symlinks = Writers.HTMLWriter.expand_versions(dirname, versions) + + # Create the versions.js file containing a list of `entries`. + # This must always happen after the folder copying. + Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries, symlinks) + + # generate the symlinks, make sure we don't overwrite devurl + cd(dirname) do + for kv in symlinks + i = findfirst(x -> x.first == devurl, symlinks) + if i === nothing + rm_and_add_symlink(kv.second, kv.first) + else + throw(ArgumentError(string("link `$(kv)` cannot overwrite ", + "`devurl = $(devurl)` with the same name."))) + end end end end @@ -734,12 +746,22 @@ filesystems that are case-insensitive (e.g. on OS X, Windows). Without doing a ` first, `git add -A` will not detect case changes in filenames. """ function gitrm_copy(src, dst) - # --ignore-unmatch so that we wouldn't get errors if dst does not exist - run(`git rm -rf --ignore-unmatch $(dst)`) - # git rm also removed parent directories + # Remove individual entries since with versions=nothing the root + # would be removed and we want to preserve previews + if isdir(dst) + for x in filter!(!in((".git", "previews")), readdir(dst)) + # --ignore-unmatch so that we wouldn't get errors if dst does not exist + run(`git rm -rf --ignore-unmatch $(joinpath(dst, x))`) + end + end + # git rm also remove parent directories # if they are empty so need to mkpath after mkpath(dst) - cp(src, dst; force=true) + # Copy individual entries rather then the full folder since with + # versions=nothing it would replace the root including e.g. the .git folder + for x in readdir(src) + cp(joinpath(src, x), joinpath(dst, x); force=true) + end end function getenv(regex::Regex) diff --git a/src/deployconfig.jl b/src/deployconfig.jl index 357783e896..6156217b15 100644 --- a/src/deployconfig.jl +++ b/src/deployconfig.jl @@ -483,9 +483,11 @@ function post_github_status(type::S, deploydocs_repo::S, sha::S, subfolder=nothi json["description"] = "Documentation build in progress" elseif type == "success" json["description"] = "Documentation build succeeded" + target_url = "https://$(owner).github.io/$(repo)/" if subfolder !== nothing - json["target_url"] = "https://$(owner).github.io/$(repo)/$(subfolder)/" + target_url *= "$(subfolder)/" end + json["target_url"] = target_url elseif type == "error" json["description"] = "Documentation build errored" elseif type == "failure"