Enable --help to provide definition items information ECFLOW-2031#400
Open
marcosbento wants to merge 6 commits into
Open
Enable --help to provide definition items information ECFLOW-2031#400marcosbento wants to merge 6 commits into
marcosbento wants to merge 6 commits into
Conversation
Scaffold the manifest for ECFLOW-2031: a new "definitions" array will
hold suite-definition-file items (node types and attributes) reached
via "ecflow_client --help=defs/<name>", a separate namespace from
commands/options/topics so that names colliding with an existing
command (e.g. the "event" attribute vs. the --event command) stay
unambiguous.
Add the definition_item schema (name, kind: node|attribute,
attaches_to required only for attributes, summary, description) and
require "definitions" at the top level. Add a "definition" topic
("List all definition-file items") and the new empty "definitions"
array to help.json. Extend the validator with a name-uniqueness check
and the embedded-newline check for the new array.
The array is empty; content authoring is a separate follow-up step.
Re ECFLOW-2031
Author every suite-definition-file item into help.json's definitions array (ECFLOW-2031): the 5 node-hierarchy types (definition, suite, family, task, alias) and 26 attributes (autoarchive through zombie), converted from docs/ug/user_manual/definition_file_format.rst's "Node Hierarchy" and "Attribute Reference" sections into plain CLI-style text. verify is deliberately excluded: it is test-tooling only, not part of the public API, and would otherwise need to carry a "DO NOT use this attribute" warning into a user-facing catalogue. User-facing Notes/Semantics content (e.g. STATE-output markers) is kept; internal ".. implementation::"-only asides and dead-end cross-references are dropped. The catalogue is data only so far -- nothing yet reads it (HelpCatalog lookup and --help dispatch wiring are separate follow-up steps). Re ECFLOW-2031
Add find_definition_item(), summary_for_definition_item(), and description_for_definition_item(), kept parallel to the existing entry_for()/summary_for()/description_for() command-and-option lookup rather than merged into it. Several definition items share a name with an existing command (event, label, meter, queue, complete) or topic (task); a shared lookup chain would make that collision ambiguous, so the two families are resolved independently and never consult each other. Extract the description-joining loop into a private join_description() helper, reused by both description_for() and the new description_for_definition_item(), instead of duplicating it. Extend TestHelpCatalog.cpp with exact lookup (found/not-found) for a node and an attribute item, summary/description accessors, and a collision-safety test asserting that every colliding name still resolves correctly through both lookup families at once. Re ECFLOW-2031
Add two new topic branches to Documentation::show(): "definition" lists every suite-definition-file item (node types and attributes), and the "defs/<name>" prefix shows detail on one specific item. The prefix, rather than a bare name, keeps every existing command/option/ topic lookup exactly as it was today -- several definition items share a name with an existing command (event, label, meter, queue, complete) or topic (task), and a bare-name lookup would make that collision ambiguous. An unknown "defs/<name>" falls back to the definition-items list (not the command list), since that is what the user was actually asking about. Update the bare --help listing to mention both new forms in its "Try:" hints and to print the definition items alongside the existing commands/options tables, re-wording a few of those hints and titles for clarity along the way. Shorten several attribute summaries in help.json (autocancel, aviso, edit, event, extern, label, late, meter, mirror, queue, repeat, time, zombie) so the new --help=definition listing reads as a scannable one-liner per item; the fuller wording remains in each item's description. Re ECFLOW-2031
Cover --help=definition (lists all 31 items), --help=defs/trigger (detail, no environment-variable footer), and an unknown --help=defs/<name> (falls back to the definition-item list, not the command list). Add a CLI-level collision-safety regression guard: event, label, meter, queue, and complete are both task commands and definition-item attribute names, and task is both a topic and a node type. Assert that the bare form still renders the command/topic unchanged while the defs/-prefixed form reaches the attribute -- exercising, through the full Documentation::show() rendering path, the same guarantee TestHelpCatalog already covers at the manifest-lookup level. Re ECFLOW-2031
Mention both in the CLI index page and the "Understanding the client" tutorial, alongside the existing --help examples. Fix a stale --help child example in that same tutorial (renamed to task earlier in this work) and a stale README claim that generating the CLI reference requires building ecflow_client -- it now reads help.json directly. Add a note on registering a new definition item there too.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #400 +/- ##
===========================================
+ Coverage 52.18% 52.24% +0.06%
===========================================
Files 1251 1251
Lines 101968 102109 +141
Branches 15171 15183 +12
===========================================
+ Hits 53210 53351 +141
Misses 48758 48758 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
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
2 participants
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.
Description
As per PR title.
Contributor Declaration
By opening this pull request, I affirm the following:
🌦️ >> Documentation << 🌦️
https://sites.ecmwf.int/docs/dev-section/ecflow/pull-requests/PR-400