Support custom tag prefix for release docs

CHANGELOG.md

@@ -32,6 +32,7 @@
 * ![Enhancement][badge-enhancement] Code blocks like `@example` or `@repl` are now also expanded in nested contexts (e.g. admonitions, lists or block quotes). ([#491][github-491], [#1970][github-1970])
 * ![Enhancement][badge-enhancement] The new `pagesonly` keyword to `makedocs` can be used to restrict builds to just the Markdown files listed in `pages` (as opposed to all `.md` files under `src/`). ([#1980][github-1980])
 * ![Enhancement][badge-enhancement] Search engine and social media link previews are now supported, with Documenter generating the relevant HTML `meta` tags. ([#1321][github-1321], [#1991][github-1991])
+* ![Enhancement][badge-enhancement] `deploydocs` now supports custom tag prefixes; see section "Deploying from a monorepo" in the docs. ([#1291][github-1291], [#1792][github-1792], [#1993][github-1993])
 * ![Bugfix][badge-bugfix] Documenter now generates the correct source URLs for docstrings from other packages when the `repo` argument to `makedocs` is set (note: the source links to such docstrings only work if the external package is cloned from GitHub and added as a dev-dependency). However, this change **breaks** the case where the `repo` argument is used to override the main package/repository URL, assuming the repository is cloned from GitHub. ([#1808][github-1808])
 * ![Bugfix][badge-bugfix] Documenter no longer uses the `TRAVIS_REPO_SLUG` environment variable to determine the Git remote of non-main repositories (when inferring it from the Git repository configuration has failed), which could previously lead to bad source links. ([#1881][github-1881])
 * ![Bugfix][badge-bugfix] Line endings in Markdown source files are now normalized to `LF` before parsing, to work around [a bug in the Julia Markdown parser][julia-29344] where parsing is sensitive to line endings, and can therefore cause platform-dependent behavior. ([#1906][github-1906])
@@ -952,6 +953,7 @@
 [github-1280]: https://github.com/JuliaDocs/Documenter.jl/pull/1280
 [github-1283]: https://github.com/JuliaDocs/Documenter.jl/pull/1283
 [github-1285]: https://github.com/JuliaDocs/Documenter.jl/pull/1285
+[github-1291]: https://github.com/JuliaDocs/Documenter.jl/issues/1291
 [github-1292]: https://github.com/JuliaDocs/Documenter.jl/pull/1292
 [github-1293]: https://github.com/JuliaDocs/Documenter.jl/pull/1293
 [github-1295]: https://github.com/JuliaDocs/Documenter.jl/pull/1295
@@ -1109,6 +1111,7 @@
 [github-1784]: https://github.com/JuliaDocs/Documenter.jl/pull/1784
 [github-1785]: https://github.com/JuliaDocs/Documenter.jl/pull/1785
 [github-1788]: https://github.com/JuliaDocs/Documenter.jl/pull/1788
+[github-1792]: https://github.com/JuliaDocs/Documenter.jl/issues/1792
 [github-1795]: https://github.com/JuliaDocs/Documenter.jl/pull/1795
 [github-1796]: https://github.com/JuliaDocs/Documenter.jl/pull/1796
 [github-1797]: https://github.com/JuliaDocs/Documenter.jl/pull/1797
@@ -1179,6 +1182,7 @@
 [github-1980]: https://github.com/JuliaDocs/Documenter.jl/pull/1980
 [github-1989]: https://github.com/JuliaDocs/Documenter.jl/pull/1989
 [github-1991]: https://github.com/JuliaDocs/Documenter.jl/pull/1991
+[github-1993]: https://github.com/JuliaDocs/Documenter.jl/pull/1993
 <!-- end of issue link definitions -->
 
 [julia-29344]: https://github.com/JuliaLang/julia/issues/29344

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