Support custom tag prefix for release docs

CHANGELOG.md

@@ -38,6 +38,7 @@
 * ![Bugfix][badge-bugfix] The default decision for whether to deploy preview builds for pull requests have been changed from `true` to `false` when not possible to verify the origin of the pull request. ([#1969][github-1969])
 * ![Maintenance][badge-maintenance] Documenter now uses [MarkdownAST][markdownast] to internally represent Markdown documents. While this change should not lead to any visible changes to the user, it is a major refactoring of the code. Please report any novel errors or unexpected behavior you encounter when upgrading to 0.28 on the [Documenter issue tracker][documenter-issues]. ([#1892][github-1892], [#1912][github-1912], [#1924][github-1924], [#1948][github-1948])
 * ![Maintenance][badge-maintenance] The code layout has changed considerably, with many of the internal submodules removed. This **may be breaking** for code that hooks into various Documenter internals, as various types and functions now live at different code paths. ([#1977][github-1977])
+* ![Enhancement][badge-enhancement] `deploydocs` now supports custom tag prefixes; see section "Deploying from a monorepo" in the docs. ([#1792][github-1792])
 
 ## Version `v0.27.23`
 

docs/src/man/hosting.md

@@ -458,13 +458,15 @@ which you can modify to something else e.g. GitHub → gh-pages, Codeberg → pa
 
 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`.
+- Documentation built for a tag `<tag_prefix>vX.Y.Z` will be stored in a folder `vX.Y.Z`, 
+  determined by the `tag_prefix` keyword to [`deploydocs`](@ref) 
+  (`""` by default).
 
 - Documentation built from the `devbranch` branch (`master` by default) is stored in a folder
   determined by the `devurl` keyword to [`deploydocs`](@ref) (`dev` by default).
 
-Which versions that will show up in the version selector is determined by the
-`versions` argument to [`deploydocs`](@ref).
+Which versions will show up in the version selector is determined by the
+`versions` argument to [`deploydocs`](@ref). For examples of non-default `tag_prefix` usage, see [Deploying from a monorepo](@ref).
 
 Unless a custom domain is being used, the pages are found at:
 
@@ -535,6 +537,90 @@ Preview builds are still deployed to the `previews` subfolder.
     ([source repository](https://github.com/JuliaDocs/juliadocs.github.io)) is one example
     where this functionality is used.
 
+
+## Deploying from a monorepo
+
+Documenter.jl supports building documentation for a package that lives in a monorepo, e.g., in a repository that contains multiple packages (including one potentially top level-)
+
+Here's one example of setting up documentation for a repository that has the following structure: one top level package and two subpackages PackageA.jl and PackageB.jl:
+```
+.
+├── README.md
+├── docs
+|   ├── make.jl
+│   └── Project.toml
+├── src/...
+├── PackageA.jl
+│   ├── docs
+|   │   ├── make.jl
+|   │   └── Project.toml
+│   └── src/...
+└── PackageB.jl
+    ├── docs
+    │   ├── make.jl
+    │   └── Project.toml
+    └── src/...
+```
+
+The three respective `make.jl` scripts should contain [`deploydocs`](@ref) settings that look something like
+
+```
+# In ./docs/make.jl
+deploydocs(; repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git",
+            # ...any additional kwargs
+            )
+
+# In ./PackageA.jl/docs/make.jl
+deploydocs(; repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git",
+             dirname="PackageA",
+             tag_prefix="PackageA-",
+             # ...any additional kwargs
+             )
+
+# In ./PackageB.jl/docs/make.jl
+deploydocs(; repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git",
+             dirname="PackageB",
+             tag_prefix="PackageB-",
+             # ...any additional kwargs
+             )
+```
+
+To build separate docs for each package, create three **separate** buildbot configurations, one for each package. Depending on the service used, the section that calls each `make.jl` script will need to be configured appropriately, e.g., 
+```
+# In the configuration file that builds docs for the top level package
+run: julia --project=docs/ docs/make.jl
+
+# In the configuration file that builds docs for PackageA.jl
+run: julia --project=PackageA.jl/docs/ PackageA.jl/docs/make.jl
+
+# In the configuration file that builds docs for PackageB.jl
+run: julia --project=PackageB.jl/docs/ PackageB.jl/docs/make.jl
+```
+
+Releases of each subpackage should be tagged with that same prefix, namely `v0.3.2` (for the top-level package), `PackageA-v0.1.2`, and `PackageB-v3.2+extra_build_tags`. which will then trigger versioned documentation deployments. Similarly to [Documentation Versions](@ref), unless a custom domain is used these three separate sets of pages will be found at:
+
+```
+https://USER_NAME.github.io/PACKAGE_NAME.jl/vX.Y.Z
+https://USER_NAME.github.io/PACKAGE_NAME.jl/dev
+https://USER_NAME.github.io/PACKAGE_NAME.jl/stable  # Links to most recent top level version
+
+https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageA/vX.Y.Z
+https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageA/dev
+https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageA/stable  # Links to most recent PackageA version
+
+https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/vX.Y.Z
+https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/dev
+https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/stable  # Links to most recent PackageB version 
+```
+
+While they won't automatically reference one another, such referencing can be added manually (e.g. by linking to https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageA/stable from the docs built for PackageB).
+
+
+!!! warning
+  When building multiple subpackages in the same repo, unique `dirname`s must be specified in each package's `deploydocs`; otherwise, only the most recently built package for a given version over the entire monorepo will be present at https://USER_NAME.github.io/PACKAGE_NAME.jl/PackageB/vX.Y.Z, and the rest of the subpackages' documentation will be unavailable.
+
+
+
 ---
 
 **Final Remarks**

src/deployconfig.jl

@@ -56,11 +56,12 @@ function documenter_key_previews(cfg::DeployConfig)
 end
 
 """
-    Documenter.deploy_folder(cfg::DeployConfig; repo, devbranch, push_preview, devurl, kwargs...)
+    Documenter.deploy_folder(cfg::DeployConfig; repo, devbranch, push_preview, devurl, 
+                             tag_prefix, kwargs...)
 
 Return a `DeployDecision`.
-This function is called with the `repo`, `devbranch`, `push_preview` and `devurl`
-arguments from [`deploydocs`](@ref).
+This function is called with the `repo`, `devbranch`, `push_preview`, `tag_prefix`,
+and `devurl` arguments from [`deploydocs`](@ref).
 
 !!! note
     Implementations of this functions should accept trailing `kwargs...` for
@@ -168,6 +169,7 @@ function deploy_folder(cfg::Travis;
                        devbranch,
                        push_preview,
                        devurl,
+                       tag_prefix = "",
                        kwargs...)
     io = IOBuffer()
     all_ok = true
@@ -189,7 +191,7 @@ function deploy_folder(cfg::Travis;
         pr_ok = cfg.travis_pull_request == "false"
         println(io, "- $(marker(pr_ok)) ENV[\"TRAVIS_PULL_REQUEST\"]=\"$(cfg.travis_pull_request)\" is \"false\"")
         all_ok &= pr_ok
-        tag_nobuild = version_tag_strip_build(cfg.travis_tag)
+        tag_nobuild = version_tag_strip_build(cfg.travis_tag; tag_prefix)
         ## If a tag exist it should be a valid VersionNumber
         tag_ok = tag_nobuild !== nothing
         all_ok &= tag_ok
@@ -309,6 +311,7 @@ function deploy_folder(cfg::GitHubActions;
                        devbranch,
                        push_preview,
                        devurl,
+                       tag_prefix = "",
                        kwargs...)
     io = IOBuffer()
     all_ok = true
@@ -332,7 +335,7 @@ function deploy_folder(cfg::GitHubActions;
         println(io, "- $(marker(event_ok)) ENV[\"GITHUB_EVENT_NAME\"]=\"$(cfg.github_event_name)\" is \"push\", \"workflow_dispatch\" or \"schedule\"")
         ## If a tag exist it should be a valid VersionNumber
         m = match(r"^refs\/tags\/(.*)$", cfg.github_ref)
-        tag_nobuild = version_tag_strip_build(m.captures[1])
+        tag_nobuild = version_tag_strip_build(m.captures[1]; tag_prefix)
         tag_ok = tag_nobuild !== nothing
         all_ok &= tag_ok
         println(io, "- $(marker(tag_ok)) ENV[\"GITHUB_REF\"]=\"$(cfg.github_ref)\" contains a valid VersionNumber")
@@ -423,7 +426,9 @@ function authenticated_repo_url(cfg::GitHubActions)
     return "https://$(ENV["GITHUB_ACTOR"]):$(ENV["GITHUB_TOKEN"])@github.com/$(cfg.github_repository).git"
 end
 
-function version_tag_strip_build(tag)
+function version_tag_strip_build(tag; tag_prefix="")
+    startswith(tag, tag_prefix) || return nothing
+    tag = replace(tag, tag_prefix => ""; count=1)
     m = match(Base.VERSION_REGEX, tag)
     m === nothing && return nothing
     s0 = startswith(tag, 'v') ? "v" : ""
@@ -432,7 +437,7 @@ function version_tag_strip_build(tag)
     s3 = m[3] === nothing ? "" : ".$(m[3])" # patch
     s4 = m[5] === nothing ? "" : m[5] # pre-release (starting with -)
     # m[7] is the build, which we want to discard
-    "$s0$s1$s2$s3$s4"
+    return "$s0$s1$s2$s3$s4"
 end
 
 function post_status(::GitHubActions; type, repo::String, subfolder=nothing, kwargs...)
@@ -598,6 +603,7 @@ function deploy_folder(
     devurl,
     branch = "gh-pages",
     branch_previews = branch,
+    tag_prefix = "",
     kwargs...,
 )
     io = IOBuffer()
@@ -621,7 +627,7 @@ function deploy_folder(
     println(io, "Detected build type: ", build_type)
 
     if build_type == :release
-        tag_nobuild = version_tag_strip_build(cfg.commit_tag)
+        tag_nobuild = version_tag_strip_build(cfg.commit_tag; tag_prefix)
         ## If a tag exist it should be a valid VersionNumber
         tag_ok = tag_nobuild !== nothing
 
@@ -740,6 +746,7 @@ function deploy_folder(
     devurl,
     branch = "gh-pages",
     branch_previews = branch,
+    tag_prefix = "",
     kwargs...,
 )
     io = IOBuffer()
@@ -761,7 +768,7 @@ function deploy_folder(
     println(io, "Detected build type: ", build_type)
 
     if build_type == :release
-        tag_nobuild = version_tag_strip_build(cfg.commit_tag)
+        tag_nobuild = version_tag_strip_build(cfg.commit_tag; tag_prefix)
         ## If a tag exist it should be a valid VersionNumber
         tag_ok = tag_nobuild !== nothing
 
@@ -936,6 +943,7 @@ function deploy_folder(
     devbranch,
     push_preview,
     devurl,
+    tag_prefix = "",
     kwargs...)
     io = IOBuffer()
     all_ok = true
@@ -963,7 +971,7 @@ function deploy_folder(
         event_ok = in(cfg.woodpecker_event_name, ["push", "pull_request", "deployment", "tag"])
         all_ok &= event_ok
         println(io, "- $(marker(event_ok)) ENV[\"CI_BUILD_EVENT\"]=\"$(cfg.woodpecker_event_name)\" is \"push\", \"deployment\" or \"tag\"")
-        tag_nobuild = version_tag_strip_build(cfg.woodpecker_tag)
+        tag_nobuild = version_tag_strip_build(cfg.woodpecker_tag; tag_prefix)
         tag_ok = tag_nobuild !== nothing
         all_ok &= tag_ok
         println(io, "- $(marker(tag_ok)) ENV[\"CI_COMMIT_TAG\"]=\"$(cfg.woodpecker_tag)\" contains a valid VersionNumber")

src/deploydocs.jl

@@ -17,6 +17,7 @@
         push_preview = false,
         repo_previews = repo,
         branch_previews = branch,
+        tag_prefix = "",
     )
 
 Copies the files generated by [`makedocs`](@ref) in `target` to the appropriate
@@ -137,6 +138,12 @@ and is usually used to install additional dependencies. By default, nothing gets
 **`make`** can be set to a function or a callable object and gets called during deployment,
 and is usually used to specify additional build steps. By default, nothing gets executed.
 
+**`tag_prefix`** can be set to allow prefixed version numbers to determine the version
+number of a release. If `tag_prefix = ""` (the default), only version tags will trigger
+deployment; with a non-empty `tag_prefix`, only version tags with that prefix will
+trigger deployment. See manual sections on [Documentation Versions](@ref) and
+[Deploying from a monorepo](@ref) for more details.
+
 # Releases vs development branches
 
 [`deploydocs`](@ref) will automatically figure out whether it is deploying the documentation
@@ -145,7 +152,8 @@ variables set by the CI system).
 
 With versioned tags, [`deploydocs`](@ref) discards the build metadata (i.e. `+` and
 everything that follows it) from the version number when determining the name of the
-directory into which the documentation gets deployed. Pre-release identifiers are preserved.
+directory into which the documentation gets deployed, as well as the `tag_prefix`
+(if present). Pre-release identifiers are preserved.
 
 # See Also
 
@@ -173,6 +181,7 @@ function deploydocs(;
         forcepush::Bool = false,
         deploy_config = auto_detect_deploy_system(),
         push_preview::Bool = false,
+        tag_prefix = "",
 
         archive = nothing, # experimental and undocumented
     )
@@ -196,7 +205,8 @@ function deploydocs(;
                                     devurl=devurl,
                                     push_preview=push_preview,
                                     repo=repo,
-                                    repo_previews=repo_previews)
+                                    repo_previews=repo_previews,
+                                    tag_prefix)
     if deploy_decision.all_ok
         deploy_branch = deploy_decision.branch
         deploy_repo = deploy_decision.repo