fix: strip Sphinx roles and directives from plain help overviews
Metadata
Current evaluation
Adds plain-help stripping for Sphinx roles and directive markers while preserving content and Markdown output; tests are included, but the PR awaits maintainer review.
Suggested action: needs review
Reason: The change directly addresses open issue craft-cli#351 and adds plain-versus-Markdown regression tests while preserving the existing Markdown path. There are no failing or pending checks and no review comments, so it appears ready for maintainer review, although the reported pre-existing test failures and absence of CI results leave some validation uncertainty.
Evaluated by: mr-cal-bot
Impact:
48
Quick Win:
20
Complexity:
46
Confidence:
82
Actionability:
78
Issue body
## Description
Overviews are shared between terminal help and rendered docs, so app authors write them with Sphinx markup. In plain terminal help that markup showed literally, e.g. an overview containing `:doc:`the tutorial <tutorials/index>`` or a `.. note::` block rendered the raw Sphinx syntax in the terminal.
Like the existing double-backtick stripping from #306, this removes Sphinx markup from plain help only:
- Roles `:role:`text``, `:domain:role:`text``, and explicit-title roles `:role:`Title <target>`` become `text` / `Title`; a leading `~` shows only the last component, as Sphinx renders it.
- Directive marker lines (`.. note::`, `.. code-block:: python`) are removed, keeping the directive content.
Markdown output is untouched, so rendered docs keep the markup.
## Related issue
Fixes #351
## Notes
- New tests mirror the #306 tests: plain help strips the markup, markdown keeps it.
- `test_command_help_text_strip_sphinx_markup` and `test_command_help_text_sphinx_markup_markdown` pass locally; the remaining failures in `tests/unit/test_help.py` are pre-existing in this environment (emitter-not-initiated errors, identical on the clean tree).
- Canonical CLA already signed (Individual).
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| minimax/minimax-m3.1-flash:free |
Impact:
48
Quick Win:
20
Complexity:
46
Confidence:
82
Actionability:
78
|
needs review | Adds plain-help stripping for Sphinx roles and directive markers while preserving content and Markdown output; tests are included, but the PR awaits maintainer review. |
Update history
| Date | Change |
|---|---|
| updated | |
| created |
Related work
-
Likely Fixed By:
craft-cli#351
(confidence 98%)
The PR description explicitly states that it fixes the open issue about removing Sphinx directives from overview texts.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #351 Remove sphinx directives from overview texts | craft-cli | open | Enhancement: strip reST/sphinx directives from command overview texts, extending the double-backtick removal done in #306; triaged, linked to CRAFT-4623, still unimplemented in helptexts.py |