Make DocumenterVitepress.deploydocs more robust + various other fixes (#257)

- Fix error when trying to read nonexistent `.vitepress/config.mts`.
- Pass `deploydocs` keyword arguments through correctly
- Respect the `dirname` keyword to deploydocs
- Compute the root directory in `DV.deploydocs` and pass it down to Documenter, so that relative `target` paths work.
- Add the correct path to the Github Actions post status JSON that Documenter pushes, by invoking it ourselves after all deployments.
- Log info statements, not warnings, when filling in missing Vitepress config files.
- Fix a bug where the `@ansi` block errored when in draft mode.

Author: asinghvi17

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.2.1 - 2025-05-15
+Bug fix release after v0.2.0 - now, namespacing deploydocs as `DocumenterVitepress.deploydocs` should "just work".
+
+- Fix error when trying to read nonexistent `.vitepress/config.mts`.
+- Pass `deploydocs` keyword arguments through correctly
+- Respect the `dirname` keyword to deploydocs
+- Compute the root directory in `DV.deploydocs` and pass it down to Documenter, so that relative `target` paths work.
+- Add the correct path to the Github Actions post status JSON that Documenter pushes, by invoking it ourselves after all deployments.
+- Log info statements, not warnings, when filling in missing Vitepress config files.
+- Fix a bug where the `@ansi` block errored when in draft mode.
+
 ## v0.2.0 - 2025-05-14
 
 - **Breaking**: `makedocs` now renders a separate build for each `base` needed by vitepress, for example `v1.2.3`, `v1.2`, `v1` and `stable`. This fixes problems stemming from the non-relocatability of vitepress sites (the base they have been rendered for must be the same as where it is deployed). Because the structure of the `build` folder changes and now contains subfolders which must be deployed separately, `Documenter.deploydocs` cannot be used anymore. Instead, use the function of similar name `DocumenterVitepress.deploydocs` which wraps Documenter's function in a way that handles the multi-folder setup correctly [#246](https://github.com/LuxDL/DocumenterVitepress.jl/pull/246). You will also have to delete every symlink on the `gh-pages` branch which Documenter has written and which you want to deploy to using DocumenterVitepress, for example `stable` will be a symlink but needs to be removed before DocumenterVitepress can render to an actual directory there. For more information check the README.

Project.toml

@@ -1,7 +1,7 @@
 name = "DocumenterVitepress"
 uuid = "4710194d-e776-4893-9690-8d956a29c365"
 authors = ["Lazaro Alonso <[email protected]>", "Anshul Singhvi <[email protected]>"]
-version = "0.2.0"
+version = "0.2.1"
 
 [deps]
 ANSIColoredPrinters = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"

README.md

@@ -25,7 +25,9 @@ pkg> add DocumenterVitepress
 To enable the backend:
 1. Add `DocumenterVitepress` to your `docs` environment using Pkg
 2. Add `using DocumenterVitepress` in `docs/make.jl`,
-3. Pass `format = DocumenterVitepress.MarkdownVitepress(...)` to `makedocs` like so, replacing e.g. `format = HTML(...)`:
+3. Pass `format = DocumenterVitepress.MarkdownVitepress(...)` to `makedocs` like so, replacing e.g. `format = HTML(...)`.
+
+(Make sure you also see the "Deploying" section below.)
 
 ```julia
 using Documenter

src/ANSIBlocks.jl

@@ -20,7 +20,7 @@ function Selectors.runner(::Type{ANSIBlocks}, node, page, doc)
     # Bail early if in draft mode
     if Documenter.is_draft(doc, page)
         @debug "Skipping evaluation of @ansi block in draft mode:\n$(x.code)"
-        page.mapping[x] = create_draft_result(x; blocktype="@ansi")
+        page.mapping[x] = Documenter.create_draft_result(x; blocktype="@ansi")
         return
     end
 

src/DocumenterVitepress.jl

@@ -111,10 +111,13 @@ function Documenter.postprocess_before_push(versions::BaseVersion; subfolder, de
 end
 
 """
-    deploydocs(; repo, target, branch, devbranch, push_preview)
+    deploydocs(; repo, target, branch, devbranch, push_preview, kwargs...)
 
 Deploy the documentation built with DocumenterVitepress.
 
+The `repo` keyword argument is required, all others are optional and default to
+the defaults of `Documenter.deploydocs` (see its documentation for more details).
+
 This function only shares a name with `Documenter.deploydocs`, it should
 therefore be invoked with `DocumenterVitepress.deploydocs`. Because of
 DocumenterVitepress's need to build a separate website for each base alias
@@ -123,13 +126,21 @@ does not work with the default settings. This function offers a wrapper over
 `Documenter.deploydocs` which deploys each separate build in sequence.
 """
 function deploydocs(;
+    root = Documenter.currentdir(),
     repo,
-    target,
-    branch,
-    devbranch,
-    push_preview,
+    target = "build",
+    dirname = "",
+    kwargs...
 )
-    bases_file = joinpath(target, "bases.txt")
+
+    if haskey(kwargs, :versions)
+        error("""
+        `DocumenterVitepress.deploydocs` does not support the `versions` keyword argument;
+        Instead, amend the `deploy_decision` you pass into `MarkdownVitepress`.
+        """)
+    end
+
+    bases_file = joinpath(root, target, "bases.txt")
     if !isfile(bases_file)
         error("Expected a file at $bases_file listing the separate bases that DocumenterVitepress has built the docs for.")
     end
@@ -140,16 +151,29 @@ function deploydocs(;
         dir = joinpath(target, "$i")
         @info "Deploying docs for base $(repr(base)) from $dir"
         Documenter.deploydocs(;
+            root,
             repo,
             target = dir, # each version built has its own dir
-            versions = DocumenterVitepress.BaseVersion(base),
-            dirname = base,
-            branch,
-            devbranch,
-            push_preview,
+            versions = DocumenterVitepress.BaseVersion(base), # the base version
+            dirname = isempty(dirname) ? base : joinpath(dirname, base), # the dirname to use
+            kwargs...
         )
     end
 
+    first_version = last(bases)
+    isempty(first_version) && return
+
+    # Push the correct version to the GH Actions documenter/deploy action.
+    # If we have reached this point, then the build was a success, so we can push
+    # the "success" type of result.
+    try
+        deploy_config = Documenter.auto_detect_deploy_system()
+        Documenter.post_status(deploy_config; type = "success", repo = repo, subfolder = first_version)
+    catch e
+        @warn "DocumenterVitepress: Error while pushing status to CI"
+        rethrow(e)
+    end
+
 end
 
 end

src/vitepress_config.jl

@@ -27,40 +27,47 @@ function modify_config_file(doc, settings, deploy_decision, i_folder, base)
 
     # Main.@infiltrate
     # Read in the config file,
-
+    # First, we establish paths to some useful directories, so that we can use them later.
     builddir = isabspath(doc.user.build) ? doc.user.build : joinpath(doc.user.root, doc.user.build)
     sourcedir = isabspath(doc.user.source) ? doc.user.source : joinpath(doc.user.root, doc.user.source)
     source_vitepress_dir = joinpath(sourcedir, ".vitepress")
     build_vitepress_dir = normpath(joinpath(builddir, settings.md_output_path, ".vitepress"))
     template_vitepress_dir = joinpath(dirname(@__DIR__), "template", "src", ".vitepress")
-    mkpath(joinpath(builddir, settings.md_output_path, ".vitepress", "theme"))
-    vitepress_config_file = joinpath(sourcedir, ".vitepress", "config.mts") # We check the source dir here because `clean=false` will persist the old, non-generated file in the build dir, and we need to overwrite it.
+
+    # Make the theme directory
+    mkpath(joinpath(build_vitepress_dir, "theme"))
+
+    # Check for the config file
+    vitepress_config_file = joinpath(source_vitepress_dir, "config.mts") # We check the source dir here because `clean=false` will persist the old, non-generated file in the build dir, and we need to overwrite it.
     if !isfile(vitepress_config_file)
         mkpath(splitdir(vitepress_config_file)[1])
-        @warn "DocumenterVitepress: Did not detect `docs/src/.vitepress/config.mts` file. Substituting in the default file."
+        @info "DocumenterVitepress: Did not detect `docs/src/.vitepress/config.mts` file. Substituting in the default file."
         # We use `write` instead of `cp` here, because `cp`'ed files inherit the permissions of the source file,
         # which may not be writable.  However, `write` creates a new file for which Julia must have write permissions.
         write(joinpath(build_vitepress_dir, "config.mts"), read(joinpath(template_vitepress_dir, "config.mts"), String))
+    else # the user has provided a config file
+        # Sometimes this file can get corrupted by makedocs(clean=false),
+        # so we need to copy it over again.
+        write(joinpath(build_vitepress_dir, "config.mts"), read(vitepress_config_file, String))
     end
 
     # ? theme / check for index.ts, style.css and docstrings.css files
     if !isfile(joinpath(source_vitepress_dir, "theme", "index.ts"))
-        @warn "DocumenterVitepress: Did not detect `docs/src/.vitepress/theme/index.ts` file. Substituting in the default file."
+        @info "DocumenterVitepress: Did not detect `docs/src/.vitepress/theme/index.ts` file. Substituting in the default file."
         write(joinpath(build_vitepress_dir, "theme", "index.ts"), read(joinpath(template_vitepress_dir, "theme", "index.ts"), String))
     end
     if !isfile(joinpath(source_vitepress_dir, "theme", "style.css"))
-        @warn "DocumenterVitepress: Did not detect `docs/src/.vitepress/theme/style.css` file. Substituting in the default file."
+        @info "DocumenterVitepress: Did not detect `docs/src/.vitepress/theme/style.css` file. Substituting in the default file."
         write(joinpath(build_vitepress_dir, "theme", "style.css"), read(joinpath(template_vitepress_dir, "theme", "style.css"), String))
     end
     if !isfile(joinpath(source_vitepress_dir, "theme", "docstrings.css"))
-        @warn "DocumenterVitepress: Did not detect `docs/src/.vitepress/theme/docstrings.css` file. Substituting in the default file."
+        @info "DocumenterVitepress: Did not detect `docs/src/.vitepress/theme/docstrings.css` file. Substituting in the default file."
         write(joinpath(build_vitepress_dir, "theme", "docstrings.css"), read(joinpath(template_vitepress_dir, "theme", "docstrings.css"), String))
     end
-    # reset the path to the variable that exists
-    vitepress_config_file_template = joinpath(source_vitepress_dir, "config.mts") # We check the source dir here because `clean=false` will persist the old, non-generated file in the build dir, and we need to overwrite it.
-    vitepress_config_file = joinpath(build_vitepress_dir, "config.mts") # We check the source dir here because `clean=false` will persist the old, non-generated file in the build dir, and we need to overwrite it.
-
-    config = read(vitepress_config_file_template, String)
+    # We have already rewritten the config file, so we can't get burned by clean=false
+    # again.
+    vitepress_config_file = joinpath(build_vitepress_dir, "config.mts")
+    config = read(vitepress_config_file, String)
     replacers = Vector{Pair{<: Union{AbstractString, Regex}, <: AbstractString}}()
 
 
@@ -148,8 +155,7 @@ function modify_config_file(doc, settings, deploy_decision, i_folder, base)
     yield()
     touch(vitepress_config_file)
 
-    #
-
+    return
 end
 
 function _get_raw_text(element)