matrei opened a new pull request, #16476:
URL: https://github.com/apache/grails-core/pull/16476
## Summary
Many cross references in the user guide go nowhere. A `<<id>>` reference to
another chapter only works in `single.html`, and some references point at
targets that exist on no page. See #16475 for the full list.
The 8.0.x-only part is in #<8.0.x PR>.
## Changes
- **Publisher:** after writing the chapter pages, `DocPublisher` points each
fragment link whose target is on another chapter page at that page, for example
`href="#multipleDatasources"` becomes `href="conf.html#multipleDatasources"`.
Links within the page, links to targets no page defines, and `single.html` are
left as they are. When several chapters define the same ID, the first one wins,
which is where the link leads in `single.html` too. On 7.0.x this covers two
links, `<<multipleDatasources>>` and the `<<interceptors>>` link taken from
8.0.x. On 8.0.x it fixes 14 once merged up, and new `<<id>>` references to
other chapters work without any special handling.
- **Guide sources:** references whose target exists on no page now use the
ID the guide actually renders:
- Spring Security: `<<voters>>`, `<<configuration>>` and
`<<installation>>` become `<<core-voters>>`, `<<cas-configuration>>`,
`<<ldap-configuration>>`, `<<rest-configuration>>` and `<<core-installation>>`.
`<<installation>>` used to lead to the Installation section of the Testing
chapter. The `xref:springSecurityCore.adoc#springSecurityCore[...]` links, and
the same for ACL and CAS, linked to pages that don't exist and become
`<<springSecurityCore,...>>`.
- Getting Started: `link:commandLine.html#customCommands` and
`link:testing.html#integrationTests` become `<<creatingCustomCommands,...>>`
and `<<integrationTesting,...>>`.
- Background Jobs: the note about `@EnableScheduling` no longer links to
the Grails 3.3 upgrade notes, which the guide no longer contains.
- Command Line, Authentication, HAL and Customizing Field Rendering:
`<<profile>>`, `<<shiro>>`, `link:#mime[...]` and `books<<0>>` get the lines
8.0.x already has, so the merge-up has nothing to reconcile there.
- **Test setup:** `grails-docs-core` can now run `DocPublisher` in tests.
This is the same setup 8.0.x has: the doc-files jar is built into its own
directory, which goes on the test runtime classpath, and `groovy-ant` and
`groovy-templates` are added.
## Merging up to 8.0.x
Two conflicts are expected. I resolved both in a trial merge with #<8.0.x
PR>, and all 52 `grails-docs-core` tests pass on the result:
- `build-logic/docs-core/build.gradle`: keep the 8.0.x `org.apache.groovy`
coordinates and the `gradleApi()` line, but declare `groovy-ant` and
`groovy-templates` as `testImplementation`. `DocPublisherSpec` compiles against
`DocPublisher`, whose signatures name their types.
- `cas/introduction.adoc`: keep the 8.0.x apereo URL and take the
`<<springSecurityCore,Spring Security Core plugin>>` link.
## Testing
- `DocPublisherSpec` publishes a three-chapter guide. It checks that
references to sections and anchors in another chapter lead to that chapter
page, that a shared anchor leads to the first chapter that defines it, that
same-page and unresolvable references are left alone, and that `single.html`
keeps plain fragments. The first feature fails without the publisher change.
- All 38 `grails-docs-core` tests pass (`cleanTest test --no-build-cache` in
`build-logic`).
- `./gradlew :grails-doc:publishGuide -x aggregateGroovydoc` builds without
errors. A scan of every relative link in the chapter pages and in `single.html`
finds none broken.
- `rat` is clean. `build-logic` has no CodeNarc or Checkstyle tasks.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
