Support deployment to the root instead of to a version subfolder, fixes

#1615. (#1616)

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

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**

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)

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"