fix(docs): display examples correctly in RTD

[dariuszd21]

• Have you followed the guidelines for contributing?
• Have you signed the CLA?
• Have you successfully run tox run -m lint?
• Have you successfully run tox run -e test-py310? (supported versions: py39, py310, py311, py312)

Some of the commands auto-generated docs were not rendered correctly, this PR addresses that

Before:

After:

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.71%. Comparing base (654871d) to head (8f69318).
Report is 634 commits behind head on main.

❗ There is a different number of reports uploaded between BASE (654871d) and HEAD (8f69318). Click for more details.

HEAD has 1 upload less than BASE

Flag	BASE (654871d)	HEAD (8f69318)
	2	1

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5139      +/-   ##
==========================================
- Coverage   94.88%   89.71%   -5.17%     
==========================================
  Files         658      342     -316     
  Lines       55189    22640   -32549     
==========================================
- Hits        52364    20311   -32053     
+ Misses       2825     2329     -496     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mr-cal]

Thanks!

As a future enhancement, we should look into doing this programmatically in craft-cli when rendering for plaintext or rst.

[mr-cal]

@medubelko - I added you to this because during planning today, we discussed if usage examples and output examples belong in the command's overview.

We didn't reach a consensus and want to get your opinion.

[medubelko]

@mr-cal

doing this programmatically

Wouldn't this require another parser, or at least another step in the doc stack?

we discussed if usage examples and output examples belong in the command's overview.

I would prefer if we generally stuck to the manpage convention:

Name
Command signature ("synopsis")
Description
Arguments

Where things get fuzzy is whether the description should contain multiple or detailed examples. I'm fine with a few, but if we start writing paragraphs where we're advising on usage (rather than agnostically describing the command) it sounds like what we really need is a how-to for the command. The LXD docs provide good examples of command how-tos. It's also best if we don't foray too far into the weeds about the nuances of individual arguments within the description. That's what the Required and Options argument sections should be for.

That said, are there cases where we want to provide all these examples in the description because the standard or global arguments are appreciably different for certain commands? If so, then we have a deeper problem related to transclusion.

[mr-cal]

@medubelko thanks, following the manpage precedent makes sense to me. And I agree that some help messages are filling in the place of missing how-tos. Not a problem I'd like to tackle today 🙈

Wouldn't this require another parser, or at least another step in the doc stack?

I think we would enhance tools/docs/gen_cli_docs.py rather than add another step. Better yet, I would upstream the rst generation from that script into craft-cli. It already has a markdown generator.

That said, are there cases where we want to provide all these examples in the description because the standard or global arguments are appreciably different for certain commands?

Nothing comes to mind for snapcraft except for snapcraft pack --output, which is on the deprecation chopping block.

[medubelko]

Approved.

@mr-cal I left a more detailed comment about the source-parser discussion in the other PR.