Skip to content

feat: add L+ Jinja report materialization - #769

Closed
AlexanderLanin wants to merge 1 commit into
eclipse-score:mainfrom
etas-contrib:lplus
Closed

feat: add L+ Jinja report materialization#769
AlexanderLanin wants to merge 1 commit into
eclipse-score:mainfrom
etas-contrib:lplus

Conversation

@AlexanderLanin

Copy link
Copy Markdown
Member

Summary

This draft PR adds the L+ proof of concept for model-complete Sphinx-Needs reports.

L+ keeps ordinary documentation reading parallel. During the read phase it records a report placeholder. After all worker environments have been merged, it renders the selected Jinja template against the resolved Needs model and materializes the resulting report in the existing document. The report outline is derived from Need links, and the template can use existing Sphinx-Needs directives such as needtable and needpie.

The previous manifest/generator experiment is intentionally not included. The report definition lives in src/needs_templates/mod_ver_report_tiny.need.

Evaluation conclusion

L+ is technically valid as a controlled solution for this report, but it is not a lightweight general-purpose extension. Sphinx does not provide a public API for adding model-complete sections and local table-of-contents entries after parallel Need collection has finished. L+ therefore needs a small compatibility layer around the cached doctree and the local ToC collector.

This makes L+ a reasonable prototype when automatic discovery from the Need graph is mandatory. It is not the simplest long-term option. If an explicit, reviewable component list is acceptable, the K approach from PR #730 is smaller, uses normal read-phase Sphinx sections and public APIs, and should be preferred.

The implementation should therefore be reviewed as an L+ experiment with a strict acceptance gate, not as proof that late materialization is a general replacement for ordinary Sphinx source processing.

Validation

  • bazel test //src/extensions/score_sphinx_needs_templates:report_pipeline_tests
  • bazel run //:docs

@github-actions

Copy link
Copy Markdown
Contributor

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run --lockfile_mode=error //src:license-check

Status: ⚠️ Needs Review

Click to expand output
[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.6.0) and connecting to it...
INFO: Invocation ID: b9b0e40f-9487-4e07-822d-5f27b1575454
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
WARNING: Target pattern parsing failed.
ERROR: Skipping '//src:license-check': no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
ERROR: no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
INFO: Elapsed time: 5.227s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

@github-actions

Copy link
Copy Markdown
Contributor

Documentation preview for this pull request is available at:
pr-769: https://eclipse-score.github.io/docs-as-code/pr-769/

@AlexanderLanin

Copy link
Copy Markdown
Member Author

moving on to #763

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

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

1 participant