Building for monorepo doesn't fully work?

[tpoisot]

I am migrating the docs for PoisotLab/SpeciesDistributionToolkit.jl to DocumenterVitepress - it's working for the main package, and I can build and preview the versions for PR for all packages nested under it, but the version of the documentation that are generated from a tag do not work.

Specifically, the site for a tagged version is pushed to PkgName/vXXX/final_site on gh-pages:

SpeciesDistributionToolkit.jl ⟩  gh-pages ⟩ ?✓ ⟩ ஃ  v1.11 
✔ ❭ ls -lah SDeMo/v0.0.7
total 4.0K
drwxr-xr-x 1 tpoisot users  64 2024-10-17 19:01 ./
drwxr-xr-x 1 tpoisot users 216 2024-10-17 19:01 ../
drwxr-xr-x 1 tpoisot users 680 2024-10-17 19:01 .documenter/
drwxr-xr-x 1 tpoisot users 262 2024-10-17 19:01 final_site/
-rw-r--r-- 1 tpoisot users  43 2024-10-17 19:01 siteinfo.js

Here is the part of docs/make.jl that should publish the website for a sub-package to its own folder:

https://github.com/PoisotLab/SpeciesDistributionToolkit.jl/blob/main/SDeMo/docs/make.jl#L39-L45

makedocs(
    sitename="SDeMo",
    format=DocumenterVitepress.MarkdownVitepress(
        repo="github.com/PoisotLab/SpeciesDistributionToolkit.jl",
        devbranch="main",
        devurl="dev",
        deploy_url="SpeciesDistributionToolkit.jl/SDeMo"
    ),
    modules=[SDeMo],
    pages=[
        "index.md",
        # ... (truncated)
    ],
)

Again, this works for the /dev/ version, and for the /previews/PRXXX/ versions, but the tagged one specifically do not work.

The fact that it goes into final_site is something I can easily fix by manually checking out gh-pages, but the other issue is that the path to the assets is wrong -- and so I need to manually modify (/sed) my way through the generated HTML to fix the path.

Is this something in the documentation that I am missing?

[asinghvi17]

I had never tested on a monorepo with multiple documentation builds so I probably missed something in the deployment pipeline. There are a couple of issues here.

• The final_site thing should be fixable - but you can pass build_vitepress=true, clean_md_output=true to DocumenterVitepress in order to enforce that.
• Not sure why the path to assets would be wrong. I looked at your gh-pages and it seems OK...is there something I am missing here? The last commit was automated, not sure if that was from your machine though. https://poisotlab.github.io/SpeciesDistributionToolkit.jl/SDeMo/dev works just fine.

[asinghvi17]

clean_md_output = isnothing(settings.clean_md_output) ? deploy_decision.all_ok : settings.clean_md_output is the way I try to get defaults out, so clearly deploy_decision.all_ok is false. This is borne out by

┌ Info: Deployment criteria for deploying release build from GitHub Actions:
│ - ✔ ENV["GITHUB_REPOSITORY"]="PoisotLab/SpeciesDistributionToolkit.jl" occurs in repo="github.com/PoisotLab/SpeciesDistributionToolkit.jl"
│ - ✔ ENV["GITHUB_EVENT_NAME"]="push" is "push", "workflow_dispatch" or "schedule"
│ - ✘ ENV["GITHUB_REF"]="refs/tags/SDeMo-v0.0.7" contains a valid VersionNumber
│ - ✔ ENV["GITHUB_ACTOR"] exists and is non-empty
│ - ✔ ENV["GITHUB_TOKEN"] exists and is non-empty
└ Deploying: ✘

because we call deploy_decision internally as well. Maybe we should always clean md output, unless it's set to false? cc @lazarusA - it was useful when I was developing the package but I guess users don't really need this stuff.

[tpoisot]

So, https://poisotlab.github.io/SpeciesDistributionToolkit.jl/SDeMo/dev/ works fine.

The stable version, https://poisotlab.github.io/SpeciesDistributionToolkit.jl/SDeMo/stable/, does not.

The docs are indeed in the final_site folder: https://poisotlab.github.io/SpeciesDistributionToolkit.jl/SDeMo/stable/final_site/

The reason why the assets don't work is that they are loaded from the wrong folder:

<script type="module" src="[/SpeciesDistributionToolkit.jl/SDeMo/assets/app.CVqJZCVh.js](view-source:https://poisotlab.github.io/SpeciesDistributionToolkit.jl/SDeMo/assets/app.CVqJZCVh.js)"></script>

Note that the /stable/ or whatever is missing from the URL.

[tpoisot]

clean_md_output = isnothing(settings.clean_md_output) ? deploy_decision.all_ok : settings.clean_md_output is the way I try to get defaults out, so clearly deploy_decision.all_ok is false. This is borne out by

This bit also tripped me up, because when using regular Documenter, it worked:

 ┌ Info: Deployment criteria for deploying release build from GitHub Actions:
│ - ✔ ENV["GITHUB_REPOSITORY"]="PoisotLab/SpeciesDistributionToolkit.jl" occurs in repo="github.com/PoisotLab/SpeciesDistributionToolkit.jl.git"
│ - ✔ ENV["GITHUB_EVENT_NAME"]="push" is "push", "workflow_dispatch" or "schedule"
│ - ✔ ENV["GITHUB_REF"]="refs/tags/SDeMo-v0.0.5" contains a valid VersionNumber
│ - ✔ ENV["GITHUB_ACTOR"] exists and is non-empty
│ - ✔ ENV["DOCUMENTER_KEY"] exists and is non-empty

[asinghvi17]

I think you can pass a deploy config in a kwarg to both MarkdownVitepress and deploy docs for now, but I'll patch the constructor so you can pass deploydocs kwargs in too

[tpoisot]

I think you can pass a deploy config in a kwarg to both MarkdownVitepress and deploy docs for now, but I'll patch the constructor so you can pass deploydocs kwargs in too

Thanks! Can you clarify what you mean by "a deploy config"? I'm kinda lost as to what precisely that is.

[tpoisot]

One additional info: when correcting the path manually, the website is broken because of 404 detection. See e.g.

https://poisotlab.github.io/SpeciesDistributionToolkit.jl/SDeMo/v0.0.6/models

I fixed the path, and it works, but the page flashes briefly before the 404 page shows up -- this is the case for any page that isn't the index.