docs: Improve model enrichment docs#2476
Open
TomCools wants to merge 2 commits into
Open
Conversation
improve model enrichment docs: TimefoldAI#2415
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the documentation around Timefold Solver Service model enrichment by moving/renaming the existing content into a dedicated page and updating navigation and cross-references accordingly.
Changes:
- Replace the old
modeling-changes.adocpage with a new, expandedmodel-enrichment.adocpage (including aliases for backwards compatibility). - Update nav and in-page references to point to the new model enrichment documentation.
- Extend the model enrichment docs with “why” and “best practices” sections.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/src/modules/ROOT/pages/running-timefold-solver/service/rest-api.adoc | Updates the note to point readers to the new model enrichment docs. |
| docs/src/modules/ROOT/pages/running-timefold-solver/service/modeling-changes.adoc | Removes the old model enrichment page content (superseded by the new page). |
| docs/src/modules/ROOT/pages/running-timefold-solver/service/model-enrichment.adoc | Adds the new, expanded model enrichment documentation page and aliases. |
| docs/src/modules/ROOT/pages/quickstart/service/getting-started.adoc | Updates the quickstart link to the new model enrichment page. |
| docs/src/modules/ROOT/nav.adoc | Replaces the old nav entry with the new model enrichment page. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Comment on lines
+35
to
+41
| Do:: | ||
| * Make enrichers idempotent: calling `enrich()` twice should produce the same result. | ||
| * Fail fast: if a required external resource is unavailable, throw an exception rather than silently returning an incomplete model. | ||
| * Use the `SolverModelEnrichmentDirector` to control ordering when one enricher depends on another. | ||
|
|
||
| Don't:: | ||
| * Do not perform heavy computation inside constraint streams. Move it to an enricher instead. |
| * Do not perform heavy computation inside constraint streams. Move it to an enricher instead. | ||
| * Do not modify planning entities' planning variables inside an enricher; only non-planning fields should be set. | ||
| * Do not keep mutable state in enrichers; they may be invoked concurrently from multiple threads. | ||
| * Do not use enrichment for validation that should happen at input time, reject bad input at the API boundary, not here. |
| ==== | ||
| This mechanism should only be used for ModelInput -> SolverModel -> ModelOutput mapping. | ||
| For enhancing the SolverModel, use the xref:./modeling-changes.adoc#solverModelEnrichment[Model Enrichment] mechanism instead. | ||
| For enhancing the SolverModel, use the xref:./model-enrichment.adoc[Model Enrichment] mechanism instead. |
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.
Improve model enrichment docs
Solves: #2415