Skip to content

docs: fix broken external and internal links in Groovydocs#15327

Open
sanjana2505006 wants to merge 1 commit intoapache:7.0.xfrom
sanjana2505006:fix/groovydoc-links
Open

docs: fix broken external and internal links in Groovydocs#15327
sanjana2505006 wants to merge 1 commit intoapache:7.0.xfrom
sanjana2505006:fix/groovydoc-links

Conversation

@sanjana2505006
Copy link
Copy Markdown
Contributor

@sanjana2505006 sanjana2505006 commented Jan 21, 2026

Changes i did:

  1. Surgical Link Correction: Modernized the docs-dependencies.gradle
    resolution logic and added a professional post-processing script (fix_groovydoc_links.py) to repair malformed relative paths for inner classes and map 20+ external API roots (Spring, Hibernate, Jakarta, GORM, etc.).

  2. Verification Tooling: Included a parallelized check_links.py utility for high-speed documentation validation.

This PR fixes issue #14991

@sanjana2505006
Copy link
Copy Markdown
Contributor Author

A small number of residual 'broken' links remain (approx. 30 reports).
My investigation confirms these are artifacts of the Groovydoc generator itself, they are 'phantom' links to generic type parameters (e.g., T1.html) or internal compiler classes that the tool references in HTML but does not actually generate as files. These do not represent errors in the documentation configuration.

@jamesfredley
Copy link
Copy Markdown
Contributor

@sanjana2505006 Thank you. On this issue would it be possible to use the python scripts to identify the source of the broken link and fix them either in the javadoc/groovy doc in each .groovy or .java file and Gradle configuration for the build? This is preferable to having a script fix them each time the project is built.

After that, if we still need to have a script, since our project is based on the Groovy programming language we prefer Groovy Scripts vs Python scripts. I don't think this should be need though, if we fix the root sources of the broken links. The broken references just built up over the last 20 years as the whole Java ecosystem has evolved significantly.

@sanjana2505006
Copy link
Copy Markdown
Contributor Author

sanjana2505006 commented Jan 21, 2026

@jamesfredley Thank you for the clarification. I’ve updated the PR to align with your suggestions.
I fixed the broken links at the source by adjusting visibility where Groovydoc couldn’t generate pages, expanded the gdoc.link configuration in docs-dependencies.gradle to cover Hibernate/GORM/Jakarta EE, and removed the Python scripts entirely. Any remaining fixes are now handled via a native Groovy Gradle task.

I’ve also squashed everything into a single commit. The docs now build cleanly with improved link resolution using the project’s native tooling.
Please let me know if you’d like anything adjusted further.

@sanjana2505006
Copy link
Copy Markdown
Contributor Author

@jamesfredley Whenever you get a chance, please review and let me know if any changes are needed

@sanjana2505006
Copy link
Copy Markdown
Contributor Author

Hello @jamesfredley, just a gentle follow-up on this PR. Whenever you have time, could you please share your feedback or let me know if any further changes are needed from my side? Happy to update anything required. Thank you

@testlens-app
Copy link
Copy Markdown

testlens-app bot commented Mar 29, 2026

✅ All tests passed ✅

🏷️ Commit: 5f0ecad
▶️ Tests: 40170 executed
⚪️ Checks: 31/31 completed


Learn more about TestLens at testlens.app.

@jdaugherty
Copy link
Copy Markdown
Contributor

There are license failures on this branch and unnecessary formatting to
unrelated areas. Can you please fix these so we can review?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

3 participants