Skip to content

PoC: generate Check docs via Maven, drop PDE-internal toc/contexts code#1364

Draft
joaodinissf wants to merge 10 commits into
dsldevkit:masterfrom
joaodinissf:check-docs-maven-poc
Draft

PoC: generate Check docs via Maven, drop PDE-internal toc/contexts code#1364
joaodinissf wants to merge 10 commits into
dsldevkit:masterfrom
joaodinissf:check-docs-maven-poc

Conversation

@joaodinissf
Copy link
Copy Markdown
Collaborator

@joaodinissf joaodinissf commented May 26, 2026

Summary

A proof of concept for generating the per-catalog Check documentation under docs/ from Maven, without an Eclipse workbench, and for taking the toc.xml / contexts.xml generators off the PDE-internal APIs they currently sit on. Two commits, both intentionally small.

Commit 1 — feat: headless CheckDocApplication + Maven wiring for HTML docs

  • New com.avaloq.tools.ddk.check.standalone.CheckDocApplication (an Eclipse IApplication) walks a source directory for .check files and emits docs/content/<Catalog>.html via the existing CheckGenerator.compileDoc template, driven by a standalone CheckStandaloneSetup injector.
  • Registered through com.avaloq.tools.ddk.check.core/plugin.xml as com.avaloq.tools.ddk.check.core.docApplication; MANIFEST.MF requires org.eclipse.equinox.app and exports the new package.
  • com.avaloq.tools.ddk.sample.helloworld/pom.xml gains an opt-in generateCheckDocs profile that runs tycho-eclipse-plugin:eclipse-run during generate-resources.

Commit 2 — feat: emit toc.xml + contexts.xml without PDE-internal APIs

  • New CheckDocumentationTemplates in com.avaloq.tools.ddk.check.generator — plain Xtend templates that emit toc.xml and contexts.xml as strings, byte-compatible with PDE's mutated output (three-space indent, alphabetic ordering, &apos; escaping). No org.eclipse.pde.internal.* imports.
  • CheckDocApplication aggregates every loaded catalog and writes one docs/toc.xml + one docs/contexts.xml for the whole project, alongside the per-catalog HTML pages.
  • The existing CheckTocGenerator / CheckContextsGenerator in com.avaloq.tools.ddk.check.ui are intentionally left in place: they still handle the IDE incremental builder path, where a single .check delta must merge into existing siblings via PDE's read-modify-write. Once the headless path proves out, those can call the new templates and drop the PDE-internal dependency entirely.

Known limitations

This is a PoC; both items are intentionally out of scope here:

  1. Reactor artifacts not visible to tycho-eclipse-plugin:eclipse-run. The plugin builds its own target platform from the configured <dependencies> and <repositories>, which does not include reactor-built bundles. So mvn -PgenerateCheckDocs verify against a clean checkout cannot find com.avaloq.tools.ddk.check.core itself. Productionising needs either a small p2 repository aggregator module or a <repositories> entry pointing at a published p2 update site for the Check bundles. The profile is documented inline with this caveat.
  2. No tests for the new templates. The templates are byte-compatible with the existing snapshot under com.avaloq.tools.ddk.check.test.runtime/docs/, but no automated assertion verifies that. A small test under com.avaloq.tools.ddk.check.core.test that runs the templates over a fixture catalog and diffs against a golden file would be a sensible follow-up.

Test plan

  • mvn -pl com.avaloq.tools.ddk.check.core -am package builds cleanly (verified locally).
  • On a workspace with the reactor-aggregator gap solved, mvn -pl com.avaloq.tools.ddk.sample.helloworld -PgenerateCheckDocs verify regenerates docs/content/*.html, docs/toc.xml, and docs/contexts.xml.
  • Eclipse-side incremental build still updates docs/ through the existing CheckBuilderParticipant path (no changes to it).
  • Compare regenerated toc.xml / contexts.xml byte-for-byte against the existing snapshot in com.avaloq.tools.ddk.check.test.runtime/docs/.

🤖 Generated with Claude Code

@joaodinissf joaodinissf force-pushed the check-docs-maven-poc branch 6 times, most recently from b5f15b7 to f9e0063 Compare May 27, 2026 09:04
joaodinissf and others added 7 commits May 27, 2026 12:20
@joaodinissf @claude
feat: headless CheckDocApplication + Maven wiring for HTML docs
87c097f 
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>
@joaodinissf @claude
feat: emit toc.xml + contexts.xml without PDE-internal APIs
d69238c 
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, &apos; 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>
@joaodinissf @claude
build: wire POC profile to reactor + Eclipse p2 sites
14b7e2f 
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>
@joaodinissf @claude
feat(check): restyle generated docs as self-contained HTML
9f4fa57 
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>
@joaodinissf @claude
build(test.runtime): add generateCheckDocs profile and refresh fixtures
7085b20 
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>
@joaodinissf @claude
docs: add downstream Tycho consumer recipe
2d57b10 
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>
@joaodinissf
feat(check): add back-link to catalog pages and filter target/ from d…
18bf6cf 
…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
@joaodinissf joaodinissf force-pushed the check-docs-maven-poc branch from f9e0063 to 18bf6cf Compare May 27, 2026 10:54
joaodinissf and others added 3 commits May 27, 2026 13:02
@joaodinissf
fix(check): exclude hidden dirs and target/ from doc walk; anchor bac…
1ab09fb 
…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
@joaodinissf
fix(check): use Path segments to exclude target/ and hidden dirs from…
924572b 
… walk
@joaodinissf @claude
fix(check): extract isUserSource predicate to satisfy checkstyle
0d11abc 
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@joaodinissf