Dispatch logic on versions when deploying (#2695)

Author: jkrumbiegel

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+* Refactored `deploydocs` internals to allow dispatch on the `versions` keyword, intended as a non-public API for DocumenterVitepress which cannot use the default versioning mechanism during deployment ([#2695]).
 * Added anchor links to admonition blocks, making it possible to create direct links to specific admonitions. ([#2505], [#2676], [#2688])
 * Added different banners for dev and unreleased docs ([#2382], [#2682])
 * Added an API function `writer_supports_ansicolor` for a Documenter writer to indicate that it supports rendering ANSI-colored strings.  This is useful for new backends that may be implemented. ([#2490])
@@ -2038,6 +2039,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2685]: https://github.com/JuliaDocs/Documenter.jl/issues/2685
 [#2692]: https://github.com/JuliaDocs/Documenter.jl/pull/2692
 [#2693]: https://github.com/JuliaDocs/Documenter.jl/issues/2693
+[#2695]: https://github.com/JuliaDocs/Documenter.jl/issues/2695
 [JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
 [JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054
 [JuliaLang/julia#39841]: https://github.com/JuliaLang/julia/issues/39841

src/deploydocs.jl

@@ -245,13 +245,10 @@ function deploydocs(;
     if deploy_decision.all_ok
         deploy_branch = deploy_decision.branch
         deploy_repo = deploy_decision.repo
-        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
+        # this dispatches on `versions` for a non-public API for DocumenterVitepress
+        deploy_subfolder = determine_deploy_subfolder(deploy_decision, versions)
 
         # Install dependencies when applicable.
         if deps !== nothing
@@ -317,7 +314,6 @@ function deploydocs(;
     return
 end
 
-
 function _get_inventory_version(objects_inv)
     return open(objects_inv) do input
         for line in eachline(input)
@@ -428,46 +424,8 @@ function git_push(
             write(joinpath(dirname, "CNAME"), cname)
         end
 
-        if versions === nothing
-            # If the documentation is unversioned and deployed to root, we generate a
-            # siteinfo.js file that would disable the version selector in the docs
-            HTMLWriter.generate_siteinfo_file(deploy_dir, nothing)
-        else
-            # Generate siteinfo-file with DOCUMENTER_CURRENT_VERSION
-            # Determine if this is a development version (e.g., "dev" or "latest")
-            is_dev_version = (subfolder == devurl || subfolder == "latest")
-            HTMLWriter.generate_siteinfo_file(deploy_dir, subfolder, is_dev_version)
-
-            # Expand the users `versions` vector
-            entries, symlinks = HTMLWriter.expand_versions(dirname, versions)
-
-            # Create the versions.js file containing a list of `entries`.
-            # This must always happen after the folder copying.
-            HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries, symlinks)
-
-            # Create the index.html file to redirect ./stable or ./dev.
-            # This must always happen after the folder copying.
-            HTMLWriter.generate_redirect_file(joinpath(dirname, "index.html"), entries)
-
-            # 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
+        # this dispatches on `versions` for a non-public API for DocumenterVitepress
+        postprocess_before_push(versions; subfolder, devurl, deploy_dir, dirname)
 
         # Add, commit, and push the docs to the remote.
         run(`$(git()) add -A -- ':!.documenter-identity-file.tmp' ':!**/.documenter-identity-file.tmp'`)
@@ -559,6 +517,68 @@ function git_push(
     return
 end
 
+# Run arbitrary logic (for example, creating siteinfo and version files)
+# on the documentation with the new additions before the changes are pushed to the remote.
+# The logic depends on the versioning scheme defined via `versions`.
+# This function was factored out as part of a non-public API via dispatch on the `versions` keyword arg
+# to `deploydocs`, for use in DocumenterVitepress because it cannot use the default versioning.
+function postprocess_before_push(versions::Nothing; subfolder, devurl, deploy_dir, dirname)
+    # If the documentation is unversioned and deployed to root, we generate a
+    # siteinfo.js file that would disable the version selector in the docs
+    HTMLWriter.generate_siteinfo_file(deploy_dir, nothing)
+    return
+end
+
+function postprocess_before_push(versions::AbstractVector; subfolder, devurl, deploy_dir, dirname)
+    # Generate siteinfo-file with DOCUMENTER_CURRENT_VERSION
+    # Determine if this is a development version (e.g., "dev" or "latest")
+    is_dev_version = (subfolder == devurl || subfolder == "latest")
+    HTMLWriter.generate_siteinfo_file(deploy_dir, subfolder, is_dev_version)
+
+    # Expand the users `versions` vector
+    entries, symlinks = HTMLWriter.expand_versions(dirname, versions)
+
+    # Create the versions.js file containing a list of `entries`.
+    # This must always happen after the folder copying.
+    HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries, symlinks)
+
+    # Create the index.html file to redirect ./stable or ./dev.
+    # This must always happen after the folder copying.
+    HTMLWriter.generate_redirect_file(joinpath(dirname, "index.html"), entries)
+
+    # generate the symlinks, make sure we don't overwrite devurl
+    return 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
+
+# Determine the subfolder to deploy to given the `deploy_decision` and the `versions`.
+# Either return a `String` or `nothing` to deploy to the root folder.
+# This function was factored out as part of a non-public API via dispatch on the `versions` keyword arg
+# to `deploydocs`, for use in DocumenterVitepress because it cannot use the default versioning.
+function determine_deploy_subfolder(deploy_decision, versions::Nothing)
+    # Non-versioned docs: deploy to root unless it's a preview
+    return deploy_decision.is_preview ? deploy_decision.subfolder : nothing
+end
+
+function determine_deploy_subfolder(deploy_decision, versions::AbstractVector)
+    return deploy_decision.subfolder
+end
+
 function rm_and_add_symlink(target, link)
     if ispath(link) || islink(link)
         @warn "removing `$(link)` and linking `$(link)` to `$(target)`."