docs: add synopsis and examples to issue and incident commands
Description
Resolves the issue and incident family findings from the style guide
audit in #8263 (closed). These two families are grouped because they share the
issuable command builders (for example, issue note and incident note
are both produced by internal/commands/issuable/note).
- Adds a Synopsis to the
issue,issue board, andincidentparent commands. - Adds a Synopsis to
issue board create,issue board view,issue create,issue delete, andissue update. - Adds Examples to
issue board create,issue board view,issue note, andincident note. ThenoteExamples come from the sharedissuable/notebuilder, so the same change covers both pages. - Adds a Synopsis note to
issue createexplaining that the--recoverflag is experimental and not ready for production use.
Each Synopsis is additive and does not repeat the Short description.
The issue, issue board, and incident parent help tests were updated
to match the rendered Synopsis (Cobra renders Long in place of Short
once Long is set).
The --output-format / -O flags on issue list and incident list
are intentionally left unchanged here (a previous output-flag MR for those
pages was closed), and the --in flag-capitalization fix on those pages
is handled separately in the quick-wins MR.
Commands updated:
issue,issue board,issue board create,issue board view,issue create,issue delete,issue update,issue noteincident,incident note
Content follows the documentation style guide and the GitLab CLI (glab) documentation style guide.
Related issues and merge requests
Documentation
If this MR adds or updates CLI command documentation, follow the conventions in the
GitLab CLI (glab) documentation style guide,
run make gen-docs, and commit the updated files in docs/source/.