Skip to content

Add option to only aggregate documentation from selected package versions#107

Open
kdayday wants to merge 11 commits into
JuliaComputing:mainfrom
kdayday:kd/version-reduction
Open

Add option to only aggregate documentation from selected package versions#107
kdayday wants to merge 11 commits into
JuliaComputing:mainfrom
kdayday:kd/version-reduction

Conversation

@kdayday
Copy link
Copy Markdown

@kdayday kdayday commented Feb 23, 2026

Summary

Adds optional control over which version directories are copied into each aggregated doc tree, and wires a “See All Versions” entry into Documenter’s version <select> that opens the upstream package site (GitHub Pages by default, or a custom URL) in a new tab. This helps when aggregating many repos with long gh-pages histories so the combined site stays closer to GitHub Pages limits (e.g. the 1 GB cap).

New MultiDocRef options

  • include_versions::Union{Vector{String}, Nothing} — When non-nothing and non-empty (e.g. ["stable", "dev"]), only those top-level version entries are copied from upstream. All root-level files (not only index.html / versions.js) are copied; .git is skipped. Version dirs are copied with follow_symlinks = true so symlinks such as stable → v1.0.0 become real directories in the aggregate.

  • all_versions_url::Union{String, Nothing} — Absolute http(s) URL used for “See All Versions” when include_versions is in use. If unset and giturl is a github.com clone URL, the URL is derived (e.g. https://github.com/org/Pkg.jl.githttps://org.github.io/Pkg.jl/). Non-GitHub hosts are not auto-derived; set all_versions_url explicitly. If neither yields a usable URL, version limiting still runs, but the extra selector option is not injected.

Behavior when include_versions is set

  • After the selective copy, the aggregate root index.html is regenerated (not taken from upstream) so it meta-refreshes to first(include_versions), avoiding stale upstream redirects (e.g. old org URLs).

  • versions.js is rewritten so DOC_VERSIONS lists only the kept versions.

  • Each processed doc HTML gets a small JSON config <script> (before </body>) consumed by assets/default/see_all_versions.js. That script appends the sentinel option, opens the target URL in a new tab on choose, and restores the dropdown. It also replaces a legacy inline “see all versions” script if present.

  • see_all_versions.js is registered as a global default script (so it ships on every build), but it only does work when the config block exists (i.e. when injection ran for that ref).

When include_versions is unset

Behavior matches main: full copy of upstream, no versions.js rewrite, no “See All Versions” injection for this feature path.

Other changes (same branch)

  • PageFind / NodeJS JLL: Harden npx / npm invocation (executable path resolution and working directory) for Windows and newer Julia where CI previously failed to spawn pagefind.

@kdayday kdayday changed the title Add option to only aggregate documentation from selected package versions [WIP] Add option to only aggregate documentation from selected package versions Feb 25, 2026
@kdayday kdayday changed the title [WIP] Add option to only aggregate documentation from selected package versions Add option to only aggregate documentation from selected package versions Apr 23, 2026
@kdayday kdayday marked this pull request as ready for review April 23, 2026 00:36
@kdayday
Copy link
Copy Markdown
Author

kdayday commented May 4, 2026

@pfitzseb Hello, is it possible to get a review on this PR? I believe the remaining Windows errors are the same as currently exist on main. Thanks so much!

@pfitzseb pfitzseb self-requested a review May 5, 2026 08:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant