Repository navigation
fix: strip Sphinx roles and directives from plain help overviews - #510
Open
Shahzeb-DataEngineer wants to merge 2 commits into
Open
Shahzeb-DataEngineer wants to merge 2 commits into
Shahzeb-DataEngineer wants to merge 2 commits into
Conversation
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. :doc:`...`, .. note::). Like the existing double-backtick stripping from canonical#306, remove Sphinx roles (keeping the readable text, explicit titles, and the last component for ~-prefixed references) and directive marker lines (keeping the directive content) from plain help only; markdown output keeps the markup for rendered docs. Fixes canonical#351 Signed-off-by: Shahzeb Ali <126076773+Shahzeb-DataEngineer@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Directive-body handling can remove literal content, and the behavior needs a changelog entry.
1 open issue
What changed in this PR
Updates plain terminal help to strip Sphinx roles and directive markers while preserving markup in Markdown output.
Changes:
- Added Sphinx role and directive filtering for plain help.
- Added tests for plain and Markdown rendering.
- A moderate issue remains with nested directive content; release-note documentation is also needed.
| File | Summary |
|---|---|
tests/unit/test_help.py |
Adds coverage for plain-help stripping and Markdown preservation. |
craft_cli/helptexts.py |
Implements Sphinx markup filtering; nested directive content handling requires correction. |
Review effort: Lite
Comment on lines
+136
to
+140
| lines = [ | ||
| line | ||
| for line in text.split("\n") | ||
| if not re.match(r"\s*\.\. [a-zA-Z][\w-]*::", line) | ||
| ] |
Contributor
Author
There was a problem hiding this comment.
Good catch, fixed in f48a5c0. The strip now tracks literal-body directives (code, code-block, raw, parsed-literal) and keeps marker-like lines inside their bodies as content, so the .. note:: example line survives. Nested real directives (e.g. a warning inside a note body) are still stripped. Also added the 3.4.2 release note.
The directive marker filter treated every indented ``.. x::`` line as a marker, so a literal ``.. note::`` line inside a ``.. code-block::`` body was stripped from plain help. Track literal-body directives (code, code-block, raw, parsed-literal) and keep marker-like lines inside them as content; nested real directives are still stripped. Also document the change in the 3.4.2 release notes. Signed-off-by: Shahzeb Ali <126076773+Shahzeb-DataEngineer@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
:role:text, `:domain:role:`text, and explicit-title roles:role:Title `` becometext/ `Title`; a leading `~` shows only the last component, as Sphinx renders it... 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
test_command_help_text_strip_sphinx_markupandtest_command_help_text_sphinx_markup_markdownpass locally; the remaining failures intests/unit/test_help.pyare pre-existing in this environment (emitter-not-initiated errors, identical on the clean tree).