[MTA 8.1.1] Updating MTA documentation for asset generation without discovery manifests

[mpershina]

Tracked under:

• Doc ticket: https://redhat.atlassian.net/browse/MTA-6832
• Engineering ticket: https://redhat.atlassian.net/browse/MTA-6788

Previews:

• CLI: https://mpershina.github.io/Previews/MTA/CLI-assets.html
• UI: https://mpershina.github.io/Previews/MTA/UI-assets.html

Summary by CodeRabbit

• Documentation
  • Clarified that the generate command supports both Kubernetes and non-Kubernetes manifests.
  • Updated procedure documentation for deployment manifest generation using discovery manifests.
  • Added information about auto-generating artifacts from Helm templates.
  • Documented fallback behavior and implicit inputs when discovery manifests are unavailable.
  • Improved code formatting in command reference documentation.

[coderabbitai]

Warning

Rate limit exceeded

@mpershina has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 44 minutes and 20 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 44 minutes and 20 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8dedb6b7-07dd-4615-8fef-5b6d81d9132a

📥 Commits

Reviewing files that changed from the base of the PR and between 028ae16 and f5688d8.

📒 Files selected for processing (5)

• assemblies/cli-guide/assembly_generating-assets.adoc
• assemblies/ui-guide/assembly_asset-generation-ui.adoc
• docs/topics/mta-cli/proc_generating-deployment-manifest.adoc
• docs/topics/mta-ui/proc_generating-deployment-assets.adoc
• docs/topics/mta-ui/proc_generating-discovery-manifest-web.adoc

📝 Walkthrough

Walkthrough

Documentation updates clarifying the discovery-manifest-driven generation workflow, explaining how the generate command produces both Kubernetes and non-Kubernetes artifacts, adding fallback behavior details when discovery manifests are unavailable, and adjusting inline code formatting in command reference.

Changes

Cohort / File(s)	Summary
Discovery Manifest Generation Workflow assemblies/cli-guide/assembly_generating-assets.adoc, docs/topics/mta-cli/proc_generating-deployment-manifest.adoc	Updated documentation to emphasize discovery-manifest-driven generation of both Kubernetes and non-Kubernetes artifacts (ConfigMap, Dockerfile). Added fallback behavior explanation for missing discovery manifests, including implicit inputs (application metadata, archetypes, tags) used for opinionated asset generation with framework-specific examples.
Command Reference Formatting docs/topics/mta-cli/ref_discover-generate-command-options.adoc	Changed placeholder formatting from italic markup to inline code backticks for discovery-manifest-name.yaml in discover cloud-foundry --output and generate helm --input option descriptions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• MTA-6439 Documentation of Dockerfile Not Generated by generate helm #343: Clarifies discovery-manifest-driven generation and non-Kubernetes output documentation for the generate helm workflow across related assembly and topic pages.
• [April CQA] MTA CLI formatting, markup, and the remaining CQA fixes #358: Modifies the same AsciiDoc files with related documentation edits to the discovery manifest generation workflow.
• [MTA] Typo fixes for MTA CLI #345: Updates the same proc_generating-deployment-manifest.adoc file with prerequisite wording adjustments.

Suggested reviewers

• gciavarrini
• rromannissen
• anarnold97

Poem

🐰 A manifest discovered,
Through documents refined,
Kubernetes and Docker both,
In clarity aligned.
Backticks now guide the way,
Generation's path is clear! 📋✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: updating MTA documentation to cover asset generation without discovery manifests, which is the core focus across all three modified documentation files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch MTA-6832

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/topics/mta-cli/proc_generating-deployment-manifest.adoc (1)

41-41: ⚠️ Potential issue | 🟡 Minor

Use underscore-style placeholder token in the command example.

_<path_to_discovery-manifest>_ should use underscores between words to match repository placeholder conventions.

Suggested fix

---input _<path_to_discovery-manifest>_ \
+--input _<path_to_discovery_manifest>_ \

Based on learnings: In this documentation repo’s AsciiDoc files, placeholder values in command examples must separate words with underscores, not hyphens.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/topics/mta-cli/proc_generating-deployment-manifest.adoc` at line 41, The
placeholder token `_ <path_to_discovery-manifest>_` uses a hyphen but must
follow the repo convention of underscore-separated words; update the command
example to use `_<path_to_discovery_manifest>_` (replace the hyphen with an
underscore) so the placeholder in the docs matches other AsciiDoc examples.

🧹 Nitpick comments (1)

assemblies/cli-guide/assembly_generating-assets.adoc (1)

34-34: Remove commented-out legacy sentence to keep docs clean.

This commented block is no longer rendered and increases maintenance noise; better to remove it from the source.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@assemblies/cli-guide/assembly_generating-assets.adoc` at line 34, Remove the
commented-out legacy sentence "//by using the discovery manifest. The deployment
manifest is generated by using a templating engine, such as Helm, that converts
the discovery manifest into a Kubernetes-native format. You can also use this
command to generate non-Kubernetes manifests, such as a Dockerfile or a
configuration file." from assembly_generating-assets.adoc to eliminate
dead/commented content; simply delete that entire commented line so only active,
rendered documentation remains.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@docs/topics/mta-cli/proc_generating-deployment-manifest.adoc`:
- Line 41: The placeholder token `_ <path_to_discovery-manifest>_` uses a hyphen
but must follow the repo convention of underscore-separated words; update the
command example to use `_<path_to_discovery_manifest>_` (replace the hyphen with
an underscore) so the placeholder in the docs matches other AsciiDoc examples.

---

Nitpick comments:
In `@assemblies/cli-guide/assembly_generating-assets.adoc`:
- Line 34: Remove the commented-out legacy sentence "//by using the discovery
manifest. The deployment manifest is generated by using a templating engine,
such as Helm, that converts the discovery manifest into a Kubernetes-native
format. You can also use this command to generate non-Kubernetes manifests, such
as a Dockerfile or a configuration file." from assembly_generating-assets.adoc
to eliminate dead/commented content; simply delete that entire commented line so
only active, rendered documentation remains.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 01433388-8a2a-480b-bc62-dd3455204bc5

📥 Commits

Reviewing files that changed from the base of the PR and between 28c1418 and 028ae16.

📒 Files selected for processing (3)

• assemblies/cli-guide/assembly_generating-assets.adoc
• docs/topics/mta-cli/proc_generating-deployment-manifest.adoc
• docs/topics/mta-cli/ref_discover-generate-command-options.adoc

[anarnold97]

This PR looks largely correct in its approach to "Asset Generation without discovery manifests." It shifts from a mandatory discovery-led workflow to a more flexible code-led approach.

Please can you check the "Transform" section of the CLI guide in the PR.

Does MTA-6788 introduce specific new flags to "simulate" a manifest? then we might have to list those in the CLI parameter tables.

[mpershina]

This PR looks largely correct in its approach to "Asset Generation without discovery manifests." It shifts from a mandatory discovery-led workflow to a more flexible code-led approach.

Please can you check the "Transform" section of the CLI guide in the PR.

Does MTA-6788 introduce specific new flags to "simulate" a manifest? then we might have to list those in the CLI parameter tables.

Hi @sjd78, could you please confirm whether there are some flags that users need to use to simulate a discovery manifest for deployment manifest generation by using the CLI? Or is it only about replacing the <path_to_discovery-manifest> input from the mta-cli generate helm --chart-dir helm_sample \ --input <path_to_discovery-manifest> \ --output-dir <location_of_deployment_manifest> \ command by something else? Could you please clarify?
TY!

[sjd78]

This PR looks largely correct in its approach to "Asset Generation without discovery manifests." It shifts from a mandatory discovery-led workflow to a more flexible code-led approach.
Please can you check the "Transform" section of the CLI guide in the PR.
Does MTA-6788 introduce specific new flags to "simulate" a manifest? then we might have to list those in the CLI parameter tables.

Hi @sjd78, could you please confirm whether there are some flags that users need to use to simulate a discovery manifest for deployment manifest generation by using the CLI? Or is it only about replacing the <path_to_discovery-manifest> input from the mta-cli generate helm --chart-dir helm_sample \ --input <path_to_discovery-manifest> \ --output-dir <location_of_deployment_manifest> \ command by something else? Could you please clarify? TY!

I'm not sure about the impact on the cli for the generators. Since generators can be anything, they may not consider the discovery manifest at all.

AFAIK, the mta-cli generate helm may require a manifest so trying to generate assets using one of these generators with an application that does not have a manifest will probably fail. That's the risk trade off when we opened the generate assets function to not require an existing manifest.

[mpershina]

This PR looks largely correct in its approach to "Asset Generation without discovery manifests." It shifts from a mandatory discovery-led workflow to a more flexible code-led approach.
Please can you check the "Transform" section of the CLI guide in the PR.
Does MTA-6788 introduce specific new flags to "simulate" a manifest? then we might have to list those in the CLI parameter tables.

Hi @sjd78, could you please confirm whether there are some flags that users need to use to simulate a discovery manifest for deployment manifest generation by using the CLI? Or is it only about replacing the <path_to_discovery-manifest> input from the mta-cli generate helm --chart-dir helm_sample \ --input <path_to_discovery-manifest> \ --output-dir <location_of_deployment_manifest> \ command by something else? Could you please clarify? TY!

I'm not sure about the impact on the cli for the generators. Since generators can be anything, they may not consider the discovery manifest at all.

AFAIK, the mta-cli generate helm may require a manifest so trying to generate assets using one of these generators with an application that does not have a manifest will probably fail. That's the risk trade off when we opened the generate assets function to not require an existing manifest.

@dymurray @rromannissen based on what Scott said, do we even want to mention anything about asset generation without a discovery manifest in the CLI doc?

[dymurray]

@mpershina I think we just remove it; not necessary to call out. But if we do this looks fine as is

[anarnold97]

LGTM - nothing to stop merging. Any suggestions are merely very minor stylistic suggestions.