feat: generate Check docs headlessly via Maven + PDE-free toc/contexts templates#1364
Draft
joaodinissf wants to merge 17 commits into
Draft
feat: generate Check docs headlessly via Maven + PDE-free toc/contexts templates#1364joaodinissf wants to merge 17 commits into
joaodinissf wants to merge 17 commits into
Conversation
joaodinissf
force-pushed
the
check-docs-maven-poc
branch
7 times, most recently
from
f9e0063 to
18bf6cf
Compare
joaodinissf
force-pushed
the
check-docs-maven-poc
branch
from
091a166 to
7492439
Compare
Add an Eclipse IApplication, com.avaloq.tools.ddk.check.standalone.CheckDocApplication, that walks a source directory for .check files and emits one docs/content/<Catalog>.html per CheckCatalog by invoking CheckGenerator.compileDoc from a standalone CheckStandaloneSetup injector — no Eclipse workbench required. The application is registered through plugin.xml under the new id com.avaloq.tools.ddk.check.core.docApplication; the new package com.avaloq.tools.ddk.check.standalone is exported and the manifest now requires org.eclipse.equinox.app. Wire it from com.avaloq.tools.ddk.sample.helloworld via an opt-in `generateCheckDocs` Maven profile that runs tycho-eclipse-plugin:eclipse-run during generate-resources. Known PoC limitation: tycho-eclipse-plugin:eclipse-run resolves the application bundle against the target platform only, so reactor-built artifacts such as check.core are not visible during a fresh build. Documented inline in the profile; productionising needs a p2 repository aggregator or a published p2 update site for the Check bundles. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add CheckDocumentationTemplates in com.avaloq.tools.ddk.check.generator — plain Xtend templates that emit the Eclipse-Help toc.xml and contexts.xml as strings, byte-compatible with what PDE used to mutate in place (three-space indent, alphabetic ordering, ' escaping). They depend only on the Check metamodel and CheckGeneratorNaming; nothing under org.eclipse.pde.internal. CheckDocApplication now aggregates every catalog it loads in one pass and writes a single docs/toc.xml + docs/contexts.xml across the whole project, alongside the per-catalog docs/content/<Catalog>.html files. The Eclipse-side CheckTocGenerator / CheckContextsGenerator under com.avaloq.tools.ddk.check.ui are left in place: they still handle the incremental IDE builder path, where a single .check delta must merge into existing siblings via PDE's read-modify-write. Eventually they can call the new templates and drop the PDE-internal dependency entirely. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The generateCheckDocs profile now declares:
- a Maven dep edge to ddk-repository so its p2 site is built before
helloworld in the reactor;
- a <repositories> list passing both that reactor p2 (file: URL) and
the Eclipse-side p2 sites (releases, EMF, xtext, MWE, Orbit) to
tycho-eclipse-plugin's eclipse-run, so check.core's transitive
requirements resolve.
Verified end-to-end: mvn -f ddk-parent/pom.xml \
-am -pl :com.avaloq.tools.ddk.sample.helloworld,:ddk-repository \
-PgenerateCheckDocs -DskipTests clean package
produces docs/toc.xml, docs/contexts.xml, and
docs/content/{LibraryChecks,ExecutionEnvironment}.html.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The per-catalog HTML used to link a stylesheet via a PLUGINS_ROOT-prefixed
URL, which only resolved inside Eclipse Help's embedded browser. Opened in
Chrome/Firefox/Safari the pages rendered unstyled.
Switch to a self-contained design:
- HTML5 doctype, viewport meta, single inline <style> block in <head>.
- Semantic body: <header> with jump-nav, <main>, <section class="category">,
<article class="check"> with anchor and color-coded severity badge,
message in <pre class="message">.
- Single STYLE constant on CheckDocumentationTemplates shared by every
page; supports prefers-color-scheme: dark.
- New compileIndex template emits docs/index.html as a landing page
listing every catalog; CheckDocApplication writes it after toc/contexts.
The external check.runtime.ui/css/check.css and its build.properties entry
become dead and are removed; grep confirmed it had no remaining consumers.
helloworld's regenerated docs are committed so the diff shows the styled
output a reviewer can preview directly.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The test.runtime bundle ships docs/{toc,contexts}.xml + docs/content/*.html
under its plugin.xml as Eclipse Help registrations. The committed HTMLs had
not been regenerated in 12 years and still linked the (now-removed) external
check.css stylesheet.
- Add the same generateCheckDocs profile already used by sample.helloworld.
- Regenerate docs/{index.html, toc.xml, contexts.xml, content/*.html}
from the bundle's own .check sources, producing the new browser-friendly
layout with severity badges and jump-nav.
Also serves as a second working example of the consumer-recipe pattern.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Document the workflow for a downstream Tycho project to consume the published p2 site and invoke the headless CheckDocApplication on its own .check sources. Covers target file entry, the ~25-line tycho-eclipse-plugin pom snippet (which differs from the in-repo POC by omitting the reactor edge), the generate-resources invocation, the output layout, and three common failure modes. Establishes the repo's docs/ convention (no top-level docs/ existed yet). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…oc walk - Add '← All catalogs' back-link at top of each per-catalog HTML page - Add .back-link CSS to shared STYLE block - Exclude target/ directories from .check file discovery so downstream repos with compiled output don't produce duplicate catalog entries
…k-link - Filter out hidden directories (.*/) and target/ from .check file discovery so compiled copies and VCS worktrees are not duplicated - Add id= to index.html <li> entries so the back-link can anchor directly to the catalog's position in the list
The inlined for-loop lambda from the previous commit tripped two
Checkstyle rules in check.core: LeftCurly (no break after the lambda's
'{') and OneStatementPerLine (multiple statements packed on one line).
Extract the per-segment filter into a named static helper so each
statement gets its own line and the call site reduces to a method
reference. No behaviour change.
Also refresh sample.helloworld/docs/* — its committed copy was stale
relative to the back-link / target-filter template changes.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
… to Java Convert the two Xtend doc-generation templates this PR touches to plain Java, so dsldevkit#1364 introduces no new Xtend (check.core is mid Xtend->Java migration; 6 of its generators are already Java). Mirrors the xtend-gen StringConcatenation building 1:1, so generated output (docs HTML, toc.xml, contexts.xml) is byte-identical (op-stream verified vs xtend-gen); matches the module's existing migrated generators. Text-block readability coalescing is a separate verified follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
joaodinissf
force-pushed
the
check-docs-maven-poc
branch
from
7492439 to
5a8be3c
Compare
… gate version Make the migrated CheckGenerator/CheckDocumentationTemplates pass checkstyle+pmd: drop 3 unused imports, add // CHECKSTYLE:CONSTANTS-OFF/ON (suppress MultipleStringLiterals for generated template literals, as sibling CheckCompiler does), and @param/@return Javadoc on the doc methods. Comment/import/Javadoc only -- generated output stays byte-identical (append op counts 512/300 unchanged). Also point the generateCheckDocs profiles at ddk-repository via ${project.parent.version} (= ddk-parent 18.0.1-SNAPSHOT) instead of the stale 17.3.0-SNAPSHOT pin, so the doc-gen gate resolves it and won't go stale again. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
compileDoc emits a '<- All catalogs' back-link (+ its CSS) that the committed snapshot predated -- regenerated via the generateCheckDocs gate (eclipse-run, now resolvable after the version fix). Confirms the Xtend->Java migration is byte-faithful: toc.xml/contexts.xml regenerated byte-identical; the only HTML delta is the back-link the generator already produces. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add CheckDocGenerationTest in check.core.test: it runs CheckGenerator.compileDoc and CheckDocumentationTemplates.compileToc/compileContexts over the ExecutionEnvironment.check / LibraryChecks.check fixtures and asserts byte-identical (LF-normalized) output against the committed snapshot copied from check.test.runtime/docs. This guards the migrated generators against silent drift in the normal CI suite (no eclipse-run, no Maven profile). Registered in CheckCoreTestSuite. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
CheckDocApplication wrote StringConcatenation output verbatim via Files.writeString; the no-arg StringConcatenation constructor picks up System.lineSeparator(), so headless regeneration on Windows produced CRLF and diverged from the LF snapshot (the in-IDE path normalizes via LfNormalizingFileSystemAccess). Route all four writes through a writeLf helper that normalizes to \n, keeping output byte-identical across platforms. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…po regen The two generateCheckDocs profiles pinned eclipse-release 2026-03 / orbit 4.39.0 while ddk-target/ddk.target is on 2026-06 / orbit 4.40.0 — doc generation resolved against a different Eclipse than the build, and the 6-entry repository block was copy-pasted across both poms. Extract the five Eclipse p2 URLs into ddk-parent properties (aligned to ddk.target) and reference them from both profiles, so they cannot drift independently. Also rewrite docs/check-doc-generation.md so it no longer contradicts the poms: add the single in-repo regeneration command (which needs the reactor p2 site and -am-built ddk-repository) and clarify that the "add the p2 site to your target platform / no <repositories> block" section is the flow for external projects documenting their own catalogs, where check.core comes from the published p2 site. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
joaodinissf
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Generates the per-catalog Check documentation under
docs/headlessly via Maven (no Eclipse workbench), and adds plain-Java templates that emittoc.xml/contexts.xmlbyte-compatible with PDE's output — so the help-system artifacts no longer have to be produced through theorg.eclipse.pde.internal.*APIs.Headless generation
com.avaloq.tools.ddk.check.standalone.CheckDocApplication(an EclipseIApplication) walks a source directory for.checkfiles and emits, via the existingCheckGenerator.compileDoctemplate and the newCheckDocumentationTemplates:docs/content/<Catalog>.html— one styled page per catalog,docs/index.html— landing page,docs/toc.xml+docs/contexts.xml— Eclipse-Help integration.check.core/plugin.xmlascom.avaloq.tools.ddk.check.core.docApplication; driven by a standaloneCheckStandaloneSetupinjector.generateCheckDocsprofile (incheck.test.runtimeandsample.helloworld) runstycho-eclipse-plugin:eclipse-runduringgenerate-resources, resolving the locally-builtcheck.corefrom the reactor p2 site.\nline endings regardless of platform, so headless regeneration on Windows stays byte-identical to the in-IDE path and the committed snapshot.PDE-free toc/contexts templates
CheckDocumentationTemplatesincheck.coreemitstoc.xmlandcontexts.xmlas strings, byte-compatible with PDE's mutated output (three-space indent, alphabetic ordering,'escaping). Noorg.eclipse.pde.internal.*imports.Regenerating the docs
From the reactor root:
See
docs/check-doc-generation.mdfor the in-repo flow and the external-consumer flow (documenting another project's catalogs against the published p2 site).Tests
CheckDocGenerationTest(check.core.test) runs the templates over theExecutionEnvironment.check/LibraryChecks.checkfixtures and asserts byte-identical*.html/toc.xml/contexts.xmlagainst the committed snapshot — drift now fails the build (runs in the normal CI suite; noeclipse-run, no profile).Scope / follow-up
The in-IDE incremental builder (
CheckBuilderParticipant) still uses the existing PDE-basedCheckTocGenerator/CheckContextsGenerator, because that path merges a single.checkdelta into existing siblings (read-modify-write) rather than regenerating whole files. Converging it onto the new whole-file templates — which removes those two generators' PDE-internal use, but is a behavioural change (incremental → full regen) on a path with no golden coverage today — is left as a dedicated follow-up. NoteCheckExtensionGenerator(plugin.xml registration) keeps a separate, unrelatedorg.eclipse.pde.internal.*dependency that this work does not touch.🤖 Generated with Claude Code