feat: add L+ Jinja report materialization - #769
Closed
AlexanderLanin wants to merge 1 commit into
Closed
Conversation
Contributor
License Check Results🚀 The license check job ran with the Bazel command: bazel run --lockfile_mode=error //src:license-checkStatus: Click to expand output |
Contributor
|
Documentation preview for this pull request is available at: |
Member
Author
|
moving on to #763 |
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
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
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
needtableandneedpie.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_testsbazel run //:docs