← Back to issue list

fix: strip Sphinx roles and directives from plain help overviews

View original Github issue

Metadata

Project
craft-cli
Number
#510
Type
pull request
State
open
Author
Shahzeb-DataEngineer
Labels
—
Created
Updated
Closed
—

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
72%